Public: anyone can read this; the crew can change it.
Every settings row carries its reason, enforced by a test over the settings registry #14098
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14071-every-settings-row-carries-its-reason-en → main 7 commits fork 3 threads · 3 unresolved
9 files
changed +129
−7
docs/design/areas/settings.md +1 −1
| @@ -34,7 +34,7 @@ its name, its control (the checkbox, select or number is the value) and a mark t | ||
| 34 | 34 | The seed changes one setting so a changed row shows beside untouched ones. |
| 35 | 35 | - `.why` — the `<details>` holding a setting's reason. Its summary is the help mark drawn as a small bordered round |
| 36 | 36 | button (28px, 44px on touch), named "Why" for a screen reader and a tooltip; open, the reason takes the full width |
| 37 | under the row. | |
| 37 | under the row. The capacity page's rows (`/settings/capacity`) carry it beside the key, in the row's title, so a row's reason is said once and its help follows as the row's own text. | |
| 38 | 38 | |
| 39 | 39 | ## Labels |
| 40 | 40 |
docs/features/capacity.md +8
| @@ -7,3 +7,11 @@ A capacity count (`crew.concurrency`, `checks.concurrency`, `queue.depth` and th | ||
| 7 | 7 | - **The pace sentence** (Home, the terminal dashboard and Usage → Spend) says "Crew concurrency is set to X, below its ceiling of Y" while `crew.concurrency` is lowered, so the cap is not mistaken for pacing. |
| 8 | 8 | |
| 9 | 9 | **Reset:** the row's **Put back** button is the reset. It is one same-origin POST to `/settings/capacity` with `reset=1`, it takes effect on the next pick, and it is logged under Changes like any other capacity change. |
| 10 | ||
| 11 | ## Why each setting is there | |
| 12 | ||
| 13 | Every capacity setting carries a required one-sentence `reason` (`CAPACITY` in | |
| 14 | `src/core/capacity.ts`; `test/settings-reasons.test.ts` fails without one, and | |
| 15 | holds the limits on `/admin/limits` to the same). `/settings/capacity` shows it | |
| 16 | first on each row, and the terminal's Capacity screen shows it as a muted line | |
| 17 | under the row. |
src/actions/capacity.ts +2
| @@ -56,6 +56,7 @@ export const SETTABLE_CAPACITY = [ | ||
| 56 | 56 | export interface CapacityRow { |
| 57 | 57 | readonly key: CapacityKey; |
| 58 | 58 | readonly label: string; |
| 59 | readonly reason: string; | |
| 59 | 60 | readonly help: string; |
| 60 | 61 | readonly value: string; |
| 61 | 62 | /** Where `value` comes from: an admin's setting, or the boot default. */ |
| @@ -145,6 +146,7 @@ function capacityRow(db: Database, key: CapacityKey, row: StoredRow | undefined) | ||
| 145 | 146 | return { |
| 146 | 147 | key, |
| 147 | 148 | label: CAPACITY[key].label, |
| 149 | reason: CAPACITY[key].reason, | |
| 148 | 150 | help: CAPACITY[key].help, |
| 149 | 151 | value: derived ? effectiveCapacity(db, key) : (stored ?? boot), |
| 150 | 152 | source: derived ? "derived" : stored === undefined ? "default" : "setting", |
src/core/capacity.ts +21 −1
| @@ -51,6 +51,8 @@ interface Definition { | ||
| 51 | 51 | readonly fallback: string; |
| 52 | 52 | /** The default from the pod's CPUs, in place of `fallback` (#2549). */ |
| 53 | 53 | readonly sized?: (cpus: number) => number; |
| 54 | /** One sentence: why the setting is there. Required; a test fails without it. */ | |
| 55 | readonly reason: string; | |
| 54 | 56 | readonly help: string; |
| 55 | 57 | } |
| 56 | 58 | |
| @@ -60,6 +62,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 60 | 62 | env: "FORGE_CREW_CONCURRENCY", |
| 61 | 63 | kind: { type: "count", min: 1, max: 16 }, |
| 62 | 64 | fallback: "2", |
| 65 | reason: "The crew shares one machine; more runs at once slow every run and every page.", | |
| 63 | 66 | help: "How many agent runs go at once. Empty: one per 3 GiB of memory above the forge's own 2 GiB, from the pod's limit, at least 2 and at most 16. Lowering it lets running ones finish; the next one waits.", |
| 64 | 67 | }, |
| 65 | 68 | "checks.concurrency": { |
| @@ -68,6 +71,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 68 | 71 | kind: { type: "count", min: 1, max: 16 }, |
| 69 | 72 | fallback: "1", |
| 70 | 73 | sized: (cpus) => checksForCpus(cpus), |
| 74 | reason: "A check runs a whole test suite; more at once starve the web process of CPU.", | |
| 71 | 75 | help: "How many repository checks run at once. Lowering it lets running ones finish; the next one waits. Empty: the pod's CPUs over three per shard (shards × 3), from 1 to 16 — 80 CPUs give 6.", |
| 72 | 76 | }, |
| 73 | 77 | "checks.shards": { |
| @@ -76,6 +80,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 76 | 80 | kind: { type: "count", min: 1, max: 32 }, |
| 77 | 81 | fallback: "1", |
| 78 | 82 | sized: (cpus) => shardsForCpus(cpus), |
| 83 | reason: "Shards cut a check's wall time, but each one is another process on the same CPUs.", | |
| 79 | 84 | help: "How many parallel shards a check's test run uses (handed to checks and crew shells as FORGE_CHECK_SHARDS). Empty: the pod's CPUs, at most 4 — and, in a check, no more than its cell holds.", |
| 80 | 85 | }, |
| 81 | 86 | "queue.depth": { |
| @@ -83,6 +88,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 83 | 88 | env: "FORGE_QUEUE_DEPTH", |
| 84 | 89 | kind: { type: "count", min: 1, max: 4 }, |
| 85 | 90 | fallback: "2", |
| 91 | reason: "Gating on top of the one before lets pulls land back to back, but every gate holds a check slot.", | |
| 86 | 92 | help: "How many merge-queue candidates of one repository gate at once, each on top of the one before: while one gates on main the next gates on it, and lands right after it if both are green. Derived from Speed (half of it rounded up, 1 to 4), read-only; FORGE_QUEUE_DEPTH is ignored. A gate beyond the first takes a free check slot only, never one of the two kept for pull checks.", |
| 87 | 93 | }, |
| 88 | 94 | "queue.batch": { |
| @@ -90,6 +96,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 90 | 96 | env: "FORGE_QUEUE_BATCH", |
| 91 | 97 | kind: { type: "count", min: 1, max: 32 }, |
| 92 | 98 | fallback: "8", |
| 99 | reason: "A bigger batch lands more per green gate, but a red one costs more gates to find its culprit.", | |
| 93 | 100 | help: "The most pulls one merge-queue candidate carries. A bigger batch lands more pulls per green gate; a red one costs more search gates to find its culprit (one bad pull in 16 is found in two rounds, at most √16 = 4 gates each). The queue starts each line here, halves the batch after a red gate and doubles it back after two green gates in a row, never past this. Read on every sweep.", |
| 94 | 101 | }, |
| 95 | 102 | "week.use": { |
| @@ -97,6 +104,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 97 | 104 | env: "FORGE_WEEK_USE", |
| 98 | 105 | kind: { type: "count", min: 10, max: 100 }, |
| 99 | 106 | fallback: "90", |
| 107 | reason: "The crew must not spend the whole week's subscription, or conversations and a person's own requests would wait.", | |
| 100 | 108 | help: "The weekly budget knob: the most of the week's subscription the crew may spend. The rest is kept for conversations and a person's own requests; the crew stops at it. Read on every pump.", |
| 101 | 109 | }, |
| 102 | 110 | "children.max": { |
| @@ -104,6 +112,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 104 | 112 | env: "FORGE_CHILDREN_MAX", |
| 105 | 113 | kind: { type: "count", min: 1, max: 1000 }, |
| 106 | 114 | fallback: "", |
| 115 | reason: "Every hosted forge holds memory and disk on this machine, so how many it holds has a top.", | |
| 107 | 116 | help: "How many hosted child forges this one holds at once. Empty: one per 512 MiB of memory above this forge's own 2 GiB, from the pod's limit. Raising it lets the New forge door open again at once.", |
| 108 | 117 | }, |
| 109 | 118 | "children.awake": { |
| @@ -111,6 +120,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 111 | 120 | env: "FORGE_CHILD_AWAKE_MAX", |
| 112 | 121 | kind: { type: "count", min: 1, max: 1000 }, |
| 113 | 122 | fallback: "8", |
| 123 | reason: "An awake forge costs resident memory; more of them than the machine holds would swap every page.", | |
| 114 | 124 | help: "How many hosted child forges run at once; a sleeping one does not count, and a new one counts from its birth. At the ceiling, the forge idle longest (no request under way, no crew at work) is put to sleep to make room, and a visitor is told the forge is full only when every awake forge is in use. Empty: one per 720 MiB of memory above this forge's own 2 GiB, from the pod's limit (an awake idle small forge costs about 490 MiB resident), at least 8. Read on every wake.", |
| 115 | 125 | }, |
| 116 | 126 | "cells.egress": { |
| @@ -120,6 +130,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 120 | 130 | env: "", |
| 121 | 131 | kind: { type: "choice", values: ["enforce", "report"] }, |
| 122 | 132 | fallback: "enforce", |
| 133 | reason: "Loosening what a cell may reach is a security decision, so it is an admin's, with a reason kept.", | |
| 123 | 134 | help: "enforce refuses a host an app or check did not declare; report lets it through on 80 and 443 and lists it on the app's page. Enforce unless an admin sets report here, with a reason. Takes effect on the next cell started.", |
| 124 | 135 | }, |
| 125 | 136 | "cells.servingCores": { |
| @@ -128,13 +139,15 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 128 | 139 | kind: { type: "count", min: 0, max: 16 }, |
| 129 | 140 | fallback: "0", |
| 130 | 141 | sized: (cpus) => servingCoresForCpus(cpus), |
| 131 | help: "Why: cells and checks busy on every core stall the forge's own serving thread, so pages wait. This many CPUs (the first ones this process may run on) are left to the forge alone; every cell and check is pinned to the rest (taskset), never more than half. 0 keeps none. Empty: none below 8 CPUs, else one per 16, 1 to 4. Without taskset nothing is pinned, and the log says so. Takes effect on the next cell started.", | |
| 142 | reason: "Cells and checks busy on every core stall the forge's own serving thread, so pages wait.", | |
| 143 | help: "This many CPUs (the first ones this process may run on) are left to the forge alone; every cell and check is pinned to the rest (taskset), never more than half. 0 keeps none. Empty: none below 8 CPUs, else one per 16, 1 to 4. Without taskset nothing is pinned, and the log says so. Takes effect on the next cell started.", | |
| 132 | 144 | }, |
| 133 | 145 | "children.modelEgress": { |
| 134 | 146 | label: "Model provider a child forge cell may reach", |
| 135 | 147 | env: "FORGE_CHILDREN_MODEL_EGRESS", |
| 136 | 148 | kind: { type: "choice", values: ["off", "openrouter", "anthropic", "both"] }, |
| 137 | 149 | fallback: "off", |
| 150 | reason: "A child's cell reaches a model provider only when its crew needs one, never by default.", | |
| 138 | 151 | help: "off keeps a child forge's cell to its parent alone; openrouter also lets it reach openrouter.ai on 443, anthropic api.anthropic.com on 443, both the two, so the child's crew can call its model on the child's own key. Nothing else opens, and the cell enforces this even when cells.egress is report. Takes effect on the next child cell started.", |
| 139 | 152 | }, |
| 140 | 153 | "children.registryEgress": { |
| @@ -142,6 +155,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 142 | 155 | env: "FORGE_CHILDREN_REGISTRY_EGRESS", |
| 143 | 156 | kind: { type: "choice", values: ["off", "npm", "build"] }, |
| 144 | 157 | fallback: "off", |
| 158 | reason: "Package registries let a child's checks fill their install cache, so they are opened on purpose.", | |
| 145 | 159 | help: "off keeps a child forge's cell from the package registries, so its checks cannot fill their install cache; npm also lets it reach registry.npmjs.org on 443; build opens the hosts ordinary app builds fetch from, on 443 alone: npm and yarn, PyPI, GitHub (git dependencies and release tarballs), crates.io and the Go module proxy. Nothing else opens, and the cell enforces this even when cells.egress is report. Takes effect on the next child cell started.", |
| 146 | 160 | }, |
| 147 | 161 | "children.paymentEgress": { |
| @@ -149,6 +163,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 149 | 163 | env: "FORGE_CHILDREN_PAYMENT_EGRESS", |
| 150 | 164 | kind: { type: "choice", values: ["off", "stripe"] }, |
| 151 | 165 | fallback: "stripe", |
| 166 | reason: "An app built in a child forge can only take a payment if its cell may reach the payment provider.", | |
| 152 | 167 | help: "stripe lets a child forge's cell reach api.stripe.com on 443, so an app a customer builds there can take a payment; off closes it. Only an app whose forge.json egress names the host reaches it: an app that does not, and the child's crew sandbox, get none of it. Nothing else opens, and the cell enforces this even when cells.egress is report. Takes effect on the next child cell started.", |
| 153 | 168 | }, |
| 154 | 169 | "children.originEgress": { |
| @@ -156,6 +171,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 156 | 171 | env: "FORGE_CHILDREN_ORIGIN_EGRESS", |
| 157 | 172 | kind: { type: "choice", values: ["off", "git"] }, |
| 158 | 173 | fallback: "git", |
| 174 | reason: "A person connecting an origin or sending a change back needs the public git hosts, and nothing else.", | |
| 159 | 175 | help: "git lets a child forge's cell reach, on 443 alone, github.com, api.github.com, codeload.github.com, gitlab.com, codeberg.org and bitbucket.org, this forge's own host, and the forges this forge holds beside it and their apps (one name ending in --<this forge's host>), so a person can connect an origin, mirror a repository they already have, and send a change back; off keeps it from all of them. No other name under this forge's domain opens, and nothing else does. It reaches a running forge at once. The switch, the other names a hosted forge may reach and what each one asked for are on Settings, Hosted forges (/settings/hosted-forges#reach).", |
| 160 | 176 | }, |
| 161 | 177 | "children.ownFilesystem": { |
| @@ -164,6 +180,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 164 | 180 | env: "", |
| 165 | 181 | kind: { type: "choice", values: ["off", "on"] }, |
| 166 | 182 | fallback: "off", |
| 183 | reason: "A child that fills a shared disk takes the forge and its siblings down with it.", | |
| 167 | 184 | help: "on refuses to start a child forge whose data directory (<data>/children/<id>) is not a filesystem of its own, so no child can fill the disk this forge and its other children share; the refusal names the child and says why. off starts it on the shared disk, held only by its cell's disk watch. Off by default, because a forge mounts nothing itself: turn it on once the platform mounts one per child. A child already running is not stopped. Read on every start.", |
| 168 | 185 | }, |
| 169 | 186 | "guard_new_accounts": { |
| @@ -171,6 +188,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 171 | 188 | env: "FORGE_GUARD_NEW_ACCOUNTS", |
| 172 | 189 | kind: { type: "choice", values: ["on", "off"] }, |
| 173 | 190 | fallback: "off", |
| 191 | reason: "Fresh accounts are where spam and abuse start, so repository creation can wait for a week.", | |
| 174 | 192 | help: "on refuses repository creation and forks for accounts younger than 7 days (agents and admins are exempt); off leaves it to the usual permissions. Takes effect immediately. Replaces the hand-installed database trigger that used to do this with no toggle.", |
| 175 | 193 | }, |
| 176 | 194 | "signin.edge": { |
| @@ -178,6 +196,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 178 | 196 | env: "FORGE_SIGNIN_EDGE", |
| 179 | 197 | kind: { type: "choice", values: ["on", "off"] }, |
| 180 | 198 | fallback: "on", |
| 199 | reason: "Trusting the platform edge's identity headers is a choice about who vouches for a person, so it can be switched off.", | |
| 181 | 200 | help: "on reads the platform edge's identity headers (when the forge has an edge secret) and offers its sign-in; off ignores them on every door, so people sign in with the forge's own methods — password and passkey. Accounts the edge made keep their names but have no password until they set one. Takes effect on the next request.", |
| 182 | 201 | }, |
| 183 | 202 | "pace.floor": { |
| @@ -185,6 +204,7 @@ export const CAPACITY: Record<CapacityKey, Definition> = { | ||
| 185 | 204 | env: "FORGE_PACE_FLOOR", |
| 186 | 205 | kind: { type: "count", min: 1, max: 16 }, |
| 187 | 206 | fallback: "2", |
| 207 | reason: "Reviews and assigned work are a person waiting, so the pace never slows them to nothing.", | |
| 188 | 208 | help: "While the week's pace allows any slots, this many reviews and issues a person assigned may run at once, apart from the crew's own picks, however hard the pace slows them; also the fewest slots a fast burn slows a repository to. At the reserve's wall everything waits. Derived from Speed (half of it, at least 1), read-only; FORGE_PACE_FLOOR is ignored; read on every pump.", |
| 189 | 209 | }, |
| 190 | 210 | }; |
src/tui/screens/capacity.ts +1
| @@ -67,6 +67,7 @@ export function capacityScreen(f: Session, ctx: Ctx): Screen { | ||
| 67 | 67 | return { |
| 68 | 68 | title: `${r.label} (${r.key})`, |
| 69 | 69 | meta: `${shown(r.value)} · ${r.source === "derived" ? "derived from Speed" : r.source} · takes ${boundsOf(r.key)}${r.source === "setting" ? ` · default ${shown(r.default)}` : ""}${low === null ? "" : ` · below ceiling ${low.ceiling}`}`, |
| 70 | note: r.reason, | |
| 70 | 71 | ...(low === null ? {} : { tone: "attn" as const }), |
| 71 | 72 | }; |
| 72 | 73 | }); |
src/web/pages/capacity.ts +4 −3
| @@ -18,6 +18,7 @@ import { field, readForm } from "../form.ts"; | ||
| 18 | 18 | import { html, when, type Html } from "../html.ts"; |
| 19 | 19 | import { flashTo } from "../layout.ts"; |
| 20 | 20 | import { badge, btn, row, time } from "../ui.ts"; |
| 21 | import { why } from "../setting_line.ts"; | |
| 21 | 22 | import { usageShell } from "./usage-tabs.ts"; |
| 22 | 23 | import { REACH_SETTINGS } from "../../actions/child_reach.ts"; |
| 23 | 24 | |
| @@ -96,18 +97,18 @@ export function capacityPage(ctx: Ctx): Response { | ||
| 96 | 97 | // It lives where a person looks for it now; this row says where, and holds no second control. |
| 97 | 98 | if (s.key === "children.originEgress") |
| 98 | 99 | return row({ |
| 99 | title: html`<span id="children-origin-egress">${s.label}</span> <span class="muted small mono">${s.key}</span>`, | |
| 100 | title: html`<span id="children-origin-egress">${s.label}</span> <span class="muted small mono">${s.key}</span> ${why(`cap-${s.key}`, s.reason)}`, | |
| 100 | 101 | meta: html`Now <span class="mono">${s.value === "git" ? "on" : "off"}</span>. This moved to |
| 101 | 102 | <a href="${REACH_SETTINGS}">Settings, Hosted forges</a>, with the other names a hosted forge may reach and what each one asked for.`, |
| 102 | 103 | trail: btn("Open it there", { href: REACH_SETTINGS, size: "sm" }), |
| 103 | 104 | }); |
| 104 | 105 | const low = belowCeiling(ctx.app.db, s.key); |
| 105 | 106 | return row({ |
| 106 | title: html`${s.label} <span class="muted small mono">${s.key}</span>${when( | |
| 107 | title: html`${s.label} <span class="muted small mono">${s.key}</span> ${why(`cap-${s.key}`, s.reason)}${when( | |
| 107 | 108 | low !== null, |
| 108 | 109 | () => html` ${badge(`below ceiling ${low?.ceiling}`, { tone: "attn" })}`, |
| 109 | 110 | )}`, |
| 110 | meta: html`${s.help} <br />Now <span class="mono">${s.value === "" ? "auto" : s.value}</span>. ${s.source === "setting" | |
| 111 | meta: html`${s.help} Now <span class="mono">${s.value === "" ? "auto" : s.value}</span>. ${s.source === "setting" | |
| 111 | 112 | ? html`Set here; the boot default is |
| 112 | 113 | <span class="mono">${s.default === "" ? "auto" : s.default}</span>${s.env === "" |
| 113 | 114 | ? "." |
test/serving-cores.test.ts +1 −1
| @@ -56,7 +56,7 @@ test("cells always keep at least half the cores", () => { | ||
| 56 | 56 | |
| 57 | 57 | test("the default keeps none below 8 CPUs, one per 16 above, at most 4", () => { |
| 58 | 58 | expect([1, 4, 7, 8, 16, 32, 64, 80, 256].map(servingCoresForCpus)).toEqual([0, 0, 0, 1, 1, 2, 4, 4, 4]); |
| 59 | expect(CAPACITY["cells.servingCores"].help).toStartWith("Why:"); | |
| 59 | expect(CAPACITY["cells.servingCores"].reason.length).toBeGreaterThan(0); | |
| 60 | 60 | }); |
| 61 | 61 | |
| 62 | 62 | test("the reserve is read from the forge's setting on every cell, 0 when unreadable", () => { |
test/settings-reasons.test.ts added +90
| @@ -0,0 +1,90 @@ | ||
| 1 | /** | |
| 2 | * Every setting row carries its reason (#14071): a registry entry without one fails the suite, and | |
| 3 | * the page shows it. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { CAPACITY, CAPACITY_KEYS } from "../src/core/capacity.ts"; | |
| 11 | import { createUser } from "../src/core/users.ts"; | |
| 12 | import { createForgeApp } from "../src/tui/forge.ts"; | |
| 13 | import { capacityScreen } from "../src/tui/screens/capacity.ts"; | |
| 14 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; | |
| 15 | import { settleApp } from "./helpers/tui.ts"; | |
| 16 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 17 | import { LIMITS, type LimitKey } from "../src/settings/limits.ts"; | |
| 18 | import { seedAdmin } from "./helpers/admin.ts"; | |
| 19 | ||
| 20 | const esc = (s: string): string => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "&9;"); | |
| 21 | const sentence = (s: unknown): boolean => typeof s === "string" && s.trim().length >= 20 && /[.!?]$/.test(s.trim()); | |
| 22 | ||
| 23 | describe("the registries", () => { | |
| 24 | test("every limit has a one-sentence reason", () => { | |
| 25 | for (const key of Object.keys(LIMITS) as LimitKey[]) expect([key, sentence(LIMITS[key].reason)]).toEqual([key, true]); | |
| 26 | }); | |
| 27 | test("every capacity setting has a one-sentence reason", () => { | |
| 28 | expect(CAPACITY_KEYS.length).toBeGreaterThan(0); | |
| 29 | for (const key of CAPACITY_KEYS) expect([key, sentence(CAPACITY[key].reason)]).toEqual([key, true]); | |
| 30 | }); | |
| 31 | }); | |
| 32 | ||
| 33 | describe("the capacity page", () => { | |
| 34 | let dataDir = ""; | |
| 35 | let app: App, servers: Servers, bearer = ""; | |
| 36 | beforeAll(async () => { | |
| 37 | dataDir = await mkdtemp(join(tmpdir(), "forge-reasons-")); | |
| 38 | app = createApp({ dataDir, port: 0 }); | |
| 39 | servers = await serve(app); | |
| 40 | const admin = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "correct-horse-battery" }); | |
| 41 | if (!admin.ok) throw new Error(admin.error); | |
| 42 | const minted = await fetch(`${servers.url}/api/v1/tokens`, { | |
| 43 | method: "POST", | |
| 44 | headers: { "content-type": "application/json" }, | |
| 45 | body: JSON.stringify({ adminConfirm: true, username: "alice", password: "correct-horse-battery", name: "cli", scope: "admin" }), | |
| 46 | }); | |
| 47 | bearer = ((await minted.json()) as { token: string }).token; | |
| 48 | }); | |
| 49 | afterAll(async () => { | |
| 50 | servers.stop(); | |
| 51 | app.close(); | |
| 52 | await rm(dataDir, { recursive: true, force: true }); | |
| 53 | }); | |
| 54 | ||
| 55 | test("shows each setting's reason in its row, the pointer row too", async () => { | |
| 56 | const res = await fetch(`${servers.url}/settings/capacity`, { headers: { authorization: `Bearer ${bearer}` } }); | |
outdated
The skip for children.originEgress leaves a row without a reason on the page. Give that row a reason and remove the skip. |
||
| 57 | expect(res.status).toBe(200); | |
| 58 | const body = await res.text(); | |
| 59 | for (const key of CAPACITY_KEYS) { | |
| 60 | const at = body.indexOf(`<details class="hint why" id="why-cap-${key}">`); | |
| 61 | expect([key, at > -1]).toEqual([key, true]); | |
| 62 | expect([key, body.indexOf(`<p>${esc(CAPACITY[key].reason)}</p>`, at) > -1]).toEqual([key, true]); | |
| 63 | } | |
| 64 | }); | |
| 65 | }); | |
outdated
This greps source text. Render the screen headlessly and assert the reason shows on screen; the test must fail if the row stops rendering it. |
||
| 66 | ||
| 67 | describe("the terminal", () => { | |
| 68 | test("shows each capacity setting's reason on the rendered screen", async () => { | |
| 69 | const dir = await mkdtemp(join(tmpdir(), "forge-reasons-tui-")); | |
| 70 | const tuiApp = createApp({ dataDir: dir, port: 0 }); | |
| 71 | try { | |
| 72 | const made = await createUser(tuiApp.db, { origin: "seed", trusted: true, username: "carol", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 73 | if (!made.ok) throw new Error(made.error); | |
| 74 | const identity = { sshUsername: "carol", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user: made.value }; | |
| 75 | const { app: tui, session } = createForgeApp(tuiApp, identity, { terminal: headlessTerminal(300, 200), exitHooks: false }); | |
| 76 | tui.start(); | |
| 77 | tui.ctx.push(capacityScreen(session, tui.ctx)); | |
| 78 | await settleApp(tui); | |
| 79 | const screen = tui.screen.toText().replace(/\s+/g, " "); | |
| 80 | for (const key of CAPACITY_KEYS) { | |
| 81 | const reason = CAPACITY[key].reason.replace(/\s+/g, " "); | |
| 82 | expect([key, screen.includes(reason)]).toEqual([key, true]); | |
| 83 | } | |
| 84 | tui.stop?.(); | |
| 85 | } finally { | |
| 86 | tuiApp.close(); | |
| 87 | await rm(dir, { recursive: true, force: true }); | |
| 88 | } | |
| 89 | }); | |
| 90 | }); |
test/tui-capacity.test.ts +1 −1
| @@ -32,7 +32,7 @@ let bot: User; | ||
| 32 | 32 | const identity = (user?: User) => ({ sshUsername: user?.username ?? "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user }); |
| 33 | 33 | const crew = () => capacityValue(app.db, "crew.concurrency"); |
| 34 | 34 | |
| 35 | function boot(user: User, rows = 40) { | |
| 35 | function boot(user: User, rows = 60) { | |
| 36 | 36 | const { app: tui, session } = createForgeApp(app, identity(user), { terminal: headlessTerminal(140, rows), exitHooks: false }); |
| 37 | 37 | tui.start(); |
| 38 | 38 | tui.ctx.push(capacityScreen(session, tui.ctx)); |
new above
offline
Principle 1 and 7:
.reasonhas no style and is not in docs/design/areas/settings.md, where.whyalready holds a setting's reason. Use the named component. Do not chain reason and help with<br />; the page says the same thing twice.