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

A forge's claim link works with scripts off: first login shows the crew working and the three next steps in the server-rendered page #14348

Merged opened this

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

Merged

scout/forge:scout/14278-a-forge-s-claim-link-works-with-scripts → main 10 commits fork 8 threads · 8 unresolved

  • Merged. scout/14278-a-forge-s-claim-link-works-with-scripts was merged into main as 647f298.

Review

Sign in to review this change.
6 files changed +130 −8
docs/features/claim-page-words.md added +24
@@ -0,0 +1,24 @@
1 ---
2 topic: Every setting, by topic
3 row: Claim page: name and next steps
4 ---
5 # Claim page: name and next steps
6
7 A new forge's claim link (`/claim`, and `/welcome` for the person who started it) answers with scripts off. The
8 server-rendered page says the forge's name once, in the sentence about who made it. Below the form it shows the crew
9 line and three next steps.
10
11 The crew line is the forge's latest public agent runs, each as what, who on which repository, and a state in plain
outdated

States the page and terminal 'cannot drift'; true only once the page renders from NEXT_STEPS. Also say what the crew line shows when the crew is working, not only when it is starting.

12 words ("working now", "waiting to start", "finished"). With no public run it says "Your crew is starting, and its first
13 public work shows here."
14
15 The three next steps are rows, each labelled by its own link: Make your account (to the form on the page), Open your
16 apps and Tell the crew. The last two pages need an account, so their notes say "after you sign in". On `/welcome`,
17 headed "Make your account" with its form above, the block lists only the two steps after it, under "Then".
18
19 Try it: `curl /claim` on a new forge, or open the link in a browser.
20
21 The terminal (both doors): the crew screen (`src/tui/screens/crew_now.ts`) shows the same runs and the same three steps.
22 Both doors render from `NEXT_STEPS` in `src/core/crew_now.ts`, so a change to a step's words changes both.
23
24 Pinned by `test/claim-page-words.test.ts` and `test/link-crew-now.test.ts`.
src/core/crew_now.ts +18
@@ -77,3 +77,21 @@ export function crewNow(db: Database): readonly CrewRun[] {
7777 state: r.state,
7878 }));
7979 }
80
81 /** One next step of a forge link's page: its words, where it goes, and what to expect. */
82 export interface NextStep {
outdated

Only the terminal consumes this; the page must too (see claim.ts). Otherwise the comment 'the terminal shows the same' is untrue.

83 readonly label: string;
84 readonly href: string;
85 readonly note: string;
86 }
87
88 /**
89 * The three next steps, in order. The page (`web/pages/claim.ts`) and the terminal
90 * (`tui/screens/crew_now.ts`) both render from this list, so they say the same. The last two
91 * pages need an account, so their notes say so.
92 */
93 export const NEXT_STEPS: readonly NextStep[] = [
94 { label: "Make your account", href: "#f-username", note: "pick a username in the form on this page" },

Principle 1: on /welcome the page heading is already 'Make your account' and the form sits directly above, so this step repeats the heading and points at the form beside it. Reword it for the page it lands on or show it only on /claim, where it is not redundant; keep the terminal list the same via this one source.

95 { label: "Open your apps", href: "/apps", note: "after you sign in, they are listed here" },
96 { label: "Tell the crew", href: "/talk", note: "after you sign in, type one thought and it gets to work" },
97 ];
src/tui/screens/crew_now.ts +4 −3
@@ -3,7 +3,7 @@
33 * (`core/crew_now.ts`), each as what, who on which repository, and its state in the page's words.
44 */
55
6 import { CREW_STARTING, crewNow, STATE_WORDS, type CrewRun } from "../../core/crew_now.ts";
6 import { CREW_STARTING, crewNow, NEXT_STEPS, STATE_WORDS, type CrewRun } from "../../core/crew_now.ts";
77 import type { Ctx, Screen } from "../app/app.ts";
88 import { style } from "../term/style.ts";
99 import { wrap } from "../term/width.ts";
@@ -11,8 +11,9 @@ import type { Session } from "../session.ts";
1111
1212 /** The screen's lines, plain data: one block per run, or the starting line. */
1313 export function crewNowLines(runs: readonly CrewRun[]): string[] {
14 if (runs.length === 0) return [CREW_STARTING];
15 return runs.flatMap((r) => [r.what, ` ${r.who} on ${r.repo}: ${STATE_WORDS[r.state]}`, ""]);
14 const steps = ["Three next steps", ...NEXT_STEPS.map((t, i) => ` ${i + 1}. ${t.label}: ${t.note}`)];
15 if (runs.length === 0) return [CREW_STARTING, "", ...steps];
16 return [...runs.flatMap((r) => [r.what, ` ${r.who} on ${r.repo}: ${STATE_WORDS[r.state]}`, ""]), ...steps];
1617 }
1718
1819 export function crewNowScreen(f: Session, ctx: Ctx, runs: readonly CrewRun[] = crewNow(f.app.db)): Screen {
src/web/pages/claim.ts +16 −3
@@ -23,7 +23,7 @@
2323 */
2424
2525 import { USERNAME_PATTERN } from "../username_pattern.ts";
26 import { crewNow } from "../../core/crew_now.ts";
26 import { crewNow, NEXT_STEPS } from "../../core/crew_now.ts";
2727 import { crewNowHtml } from "../crew_now.ts";
2828 import { PASSWORD_TOO_LONG, withinPasswordCap } from "../../core/hash-gate.ts";
2929 import { givenEmail, MIN_SIGNUP_PASSWORD, noEmail } from "../../actions/users.ts";
@@ -222,6 +222,17 @@ function takeover(ctx: Ctx, spawned: Spawned, spawner: User | undefined): Html |
222222 return html`<p class="mb" id="claim-takeover">Choose a username of your own. Choosing ${spawner.username} instead takes over the account ${spawner.username} set this forge up with, and everything already made under it.</p>`;
223223 }
224224
225 /**
226 * The next steps from `NEXT_STEPS`, one row each: the step's own link is the row's label, its
227 * note beside it, plain links that work with scripts off. On /welcome the page heading is the
228 * first step and its form sits above, so that page lists only the steps after it.
outdated

Principle 7/8: labels are typed here and again in NEXT_STEPS (src/core/crew_now.ts). Render the page from NEXT_STEPS (href per index) so the two doors really share one source. Also hand-rolled class="list"/h2 small markup: use the named rows component from docs/DESIGN.md and run bun scripts/design-lint.ts. Un-export nextSteps unless something imports it.

229 */
outdated

The step 'Make your account' repeats the page heading directly above it (principle 1: nothing explains itself twice). Before sign-in, 'Open your apps' and 'Tell the crew' link to pages that bounce to sign-in; say so in the link text in plain words, or drop them as links until an account exists.

outdated

Principle 1: the block already says 'Three next steps' in its heading, and each row then adds a 'Step 1/2/3' label, so it explains the order twice. Use the step's own label as the row's dt (or an ordered list of rows) and drop the 'Step N' text.

230 function nextSteps(afterAccount = false): Html {
231 const steps = afterAccount ? NEXT_STEPS.slice(1) : NEXT_STEPS;
232 return html`<section id="next-steps" class="mt" aria-label="Next steps"><h2 class="small">${afterAccount ? "Then" : "Three next steps"}</h2>
233 <dl class="status-rows">${steps.map((s) => html`<div class="status-row"><dt><a href="${s.href}">${s.label}</a></dt><dd>${s.note}</dd></div>`)}</dl></section>`;
234 }
235
225236 function claimForm(
226237 ctx: Ctx,
227238 spawned: Spawned,
@@ -236,15 +247,16 @@ function claimForm(
236247 return html`<div class="shell"><div class="narrow">
237248 ${pageHead("Make your account")}
outdated

Principle 1/7: the forge name is a bare paragraph, and the next paragraph's sentence names it again. Make it a dl row ('Forge' / name) or put it in the heading, and drop one of the two mentions.

238249 <section class="settings-block">
239 <p class="mb">Pick a username, then create your passkey. You will be the admin of this forge.</p>
250 <p class="mb" id="forge-name">Pick a username, then create your passkey. You will be the admin of ${spawned.org.username}.</p>
240251 ${accountForm(ctx, "/welcome", values, errors)}
241252 </section>
242253 ${crewNowHtml(crewNow(ctx.app.db))}
254 ${nextSteps(true)}
243255 </div></div>`;
244256 return html`<div class="shell"><div class="narrow">
245257 ${pageHead("This forge is yours")}
246258 <section class="settings-block">
247 <p class="mb">${spawner === undefined ? `${spawned.org.username} was made` : `${spawner.username} made ${spawned.org.username}`} for you. Your account will be its admin, so it can change everything here.</p>
259 <p class="mb" id="forge-name">${spawner === undefined ? `${spawned.org.username} was made` : `${spawner.username} made ${spawned.org.username}`} for you. Your account will be its admin, so it can change everything here.</p>
248260 ${expiresAt === undefined
249261 ? null
250262 : html`<p class="mb" id="claim-expiry">This link works until
@@ -256,6 +268,7 @@ function claimForm(
256268 ${accountForm(ctx, "/claim", values, errors)}
257269 </section>
258270 ${crewNowHtml(crewNow(ctx.app.db))}
271 ${nextSteps()}
259272 </div></div>`;
outdated

Misindented (6 spaces, sibling of crewNowHtml has 4). Align with the line above.

260273 }
261274
test/claim-page-words.test.ts +65
@@ -15,6 +15,9 @@ import { createUser } from "../src/core/users.ts";
1515 import { serve, type Servers } from "../src/http/server.ts";
1616 import { firstBoot } from "../src/spawn/first-boot.ts";
1717 import { relativeWords } from "../src/web/pages/claim.ts";
18 import { createRepo } from "../src/actions/repos.ts";
19 import { claimRun, createRun } from "../src/core/runs.ts";
20 import { NEXT_STEPS, STATE_WORDS } from "../src/core/crew_now.ts";
1821 import { quietLogs } from "./helpers/globals.ts";
1922
2023 quietLogs();
@@ -143,3 +146,65 @@ describe("the claim page in plain words", () => {
143146 expect(res.status).toBe(404);
144147 });
145148 });
149
150 describe("the claim page with scripts off", () => {
151 test("shows the forge name once, the crew line (starting and working) and the three next steps", async () => {
152 const dir = await mkdtemp(join(tmpdir(), "forge-claim-steps-"));
153 const parent = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
154 const alice = await createUser(parent.db, {
155 origin: "seed", trusted: true, username: "alice", email: "[email protected]",
156 password: "a-long-claim-passphrase", isAdmin: true,
157 });
158 if (!alice.ok) throw new Error("user");
159 const rw = createToken(parent.db, alice.value.id, "rw", "rw").token;
160 const servers = await serve(parent);
161 const made = await fetch(`${servers.url}/api/v1/forges`, {
162 method: "POST",
163 headers: { authorization: `Bearer ${rw}`, "content-type": "application/json" },
164 body: JSON.stringify({ name: "stepsforge", apps: [], dryRun: false }),
165 });
166 const body = (await made.json()) as { bodyId: string };
167 const child = createApp({ dataDir: childDirOf(parent, body.bodyId), port: 0 });
168 await firstBoot(child);
169 const cs = await serve(child);
170 const page = async (path: string) => (await fetch(`${cs.url}${path}`)).text();
171 const within = (text: string, id: string) =>
outdated

Box 3 asks for a working crew line. This only asserts 'Your crew is starting'. Seed a public run in the child and assert its 'working now' wording; assert #next-steps and the forge name is within #forge-name. Also assert /welcome (the own branch), which the diff changes but no test covers.

172 new RegExp(`id="${id}"[^>]*>([\\s\\S]*?)</(p|section)>`).exec(text)?.[1] ?? "";
173 for (const path of ["/claim", "/welcome"]) {
174 const text = await page(path);
175 expect(within(text, "forge-name")).toContain("stepsforge");
176 expect(text).toContain('id="crew-now"');
177 expect(text).toContain("Your crew is starting");
178 const steps = within(text, "next-steps");
179 // The page renders from the one list the terminal reads.
180 // Each row is labelled by its own step, never by a "Step N" that repeats the heading.
181 expect(steps).not.toMatch(/Step \d/);
182 // /welcome is headed "Make your account" with its form above, so it lists only what follows.
183 const shown = path === "/welcome" ? NEXT_STEPS.slice(1) : NEXT_STEPS;
184 for (const s of shown) {
185 expect(steps).toContain(`<dt><a href="${s.href}">${s.label}</a></dt>`);
186 expect(steps).toContain(s.note);
187 }
188 if (path === "/welcome") expect(steps).not.toContain(NEXT_STEPS[0]!.label);
189 expect(text.split("stepsforge").length - 1).toBe(1);
190 }
191 // A public run in work shows in the page's words for a working crew.
192 const maker = await createUser(child.db, {
193 origin: "seed", trusted: true, username: "maker", email: "[email protected]", password: "a-long-claim-passphrase", isAdmin: true,
194 });
195 if (!maker.ok) throw new Error("user");
196 const repo = await createRepo(child, maker.value, { name: "hello", visibility: "public" });
197 if (!repo.ok) throw new Error(String(repo.error));
198 const run = createRun(child.db, { repoId: repo.value.id, kind: "agent", reason: "tidy the readme" });
199 claimRun(child.db, run.id);
200 const working = await page("/claim");
201 expect(within(working, "crew-now")).toContain("tidy the readme");
202 expect(working).toContain(STATE_WORDS.running);
203 expect(working).not.toContain("Your crew is starting");
204 cs.stop();
205 child.close();
206 servers.stop();
207 parent.close();
208 await rm(dir, { recursive: true, force: true });
209 }, 60_000);
210 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs