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

A new forge's first login shows three next steps as three plain links and hides them once each is done #13496

Merged opened this

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

Merged

scout/forge:scout/13460-a-new-forge-s-first-login-shows-three-ne → main 7 commits fork 2 threads · 2 unresolved

  • Merged. scout/13460-a-new-forge-s-first-login-shows-three-ne was merged into main as 13240e9.

Review

Sign in to review this change.
9 files changed +199 −6
docs/design/attention-budget.json +6 −5
@@ -1,15 +1,16 @@
11 {
22 "home": {
33 "390": {
4 "words": 286,
5 "blocks": 49,
4 "words": 297,
5 "blocks": 50,
66 "colours": 7
77 },
88 "1280": {
9 "words": 286,
10 "blocks": 49,
9 "words": 297,
10 "blocks": 50,
1111 "colours": 7
12 }
12 },
13 "note": "Raised by 11 words and 1 block for the first-week line (To start: three links), shown to an admin in a forge's first week only (#13460)."
1314 },
1415 "repository": {
1516 "390": {
docs/features/README.md +1
@@ -17,6 +17,7 @@ A new note gets a row here (`test/feature-orphans.test.ts`).
1717 Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
1818
1919 - [A forge made from a template says so on its home](started-from.md)
20 - [First week: three steps on a new forge's home](first-week.md)
2021 - [How long the last forge from a template took, at /templates/<name>](template-timing.md)
2122 - [A look in the feed](feed-look.md)
2223 - [Open pulls red for over a day are named in one issue](red-pulls.md)
docs/features/first-week.md added +7
@@ -0,0 +1,7 @@
1 # First week
2
3 On a forge whose first account is under seven days old, its admin sees one line at the top of home: `To start:` and three links, Name an app, Tell the crew something, Invite someone. A step already done is struck through. When all three are done, or the forge is a week old, the line is gone. The terminal home shows the same line.
4
5 Each step is read from records that already exist, nothing is stored: an app is any repository the admin owns; telling is an issue they wrote that is not an app's direction issue; inviting is an invite link they made. A spawned forge keeps its own, longer first-login card instead.
6
7 Code: `src/core/first_week.ts` (the steps), `src/web/first_week.ts` (the line). Test: `test/first-week.test.ts`.
src/core/first_week.ts added +47
@@ -0,0 +1,47 @@
1 /**
2 * The first week's three steps for the person who set a forge up: name an app, tell the crew
3 * something, invite someone. Each is read from records that already exist (a repository they own,
4 * an issue they wrote, an invite they made); nothing is stored. Only a person who is a site admin
5 * sees them, and only while the forge's first account is under seven days old. Once all three are
6 * done there are none.
7 */
8
9 import type { Database } from "bun:sqlite";
10 import type { User } from "./users.ts";
11
12 export const FIRST_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
13
14 export type FirstWeekKey = "app" | "tell" | "invite";
15
16 export interface FirstWeekStep {
17 readonly key: FirstWeekKey;
18 readonly text: string;
19 readonly href: string;
20 readonly done: boolean;
21 }
22
23 /**
24 * The steps, or null when the forge is a week old or more, the viewer is not its admin, or all are
25 * done.
26 */
27 export function firstWeekSteps(db: Database, user: User | undefined, now: number = Date.now()): readonly FirstWeekStep[] | null {
28 if (user === undefined || user.kind !== "user" || !user.isAdmin) return null;
29 const born = db.query<{ at: string | null }, []>("SELECT MIN(created_at) AS at FROM user").get()?.at;
30 const since = born ? Date.parse(born) : Number.NaN;
31 if (!Number.isFinite(since) || now - since >= FIRST_WEEK_MS) return null;
32 const has = (sql: string): boolean => db.query<{ n: number }, [string]>(sql).get(user.id) !== null;
33 const steps: FirstWeekStep[] = [
34 { key: "app", text: "Name an app", href: "/new", done: has("SELECT 1 AS n FROM repo WHERE owner_id = ?1 LIMIT 1") },
35 {
36 key: "tell",
37 text: "Tell the crew something",
38 href: "#tell-box",
39 done: has(
40 `SELECT 1 AS n FROM issue WHERE kind = 'issue' AND author_id = ?1
41 AND id NOT IN (SELECT direction_issue_id FROM repo WHERE direction_issue_id IS NOT NULL) LIMIT 1`,
42 ),
43 },
44 { key: "invite", text: "Invite someone", href: "/admin/limits", done: has("SELECT 1 AS n FROM invite WHERE created_by = ?1 LIMIT 1") },
45 ];
46 return steps.every((s) => s.done) ? null : steps;
47 }
src/spawn/live.ts +4 −1
@@ -16,7 +16,10 @@ export const SLOW_POLL_MS = 5000;
1616 /** At most this many watchers at once per forge; a spawn past it is made but not timed. */
1717 export const MAX_WATCHERS = 20;
1818 const open = new WeakMap<App, number>();
19 /** Give up after this long: well past the 3-minute budget, so a slow forge still counts as live, late. */
19 /**
20 * Give up after this long: well past the 3-minute budget, so a slow forge still counts as live,
21 * late.
22 */
2023 export const GIVE_UP_MS = 10 * 60_000;
2124
2225 export type Probe = () => Promise<boolean>;
src/tui/screens/dashboard.ts +9
@@ -33,6 +33,7 @@ import { crewCanRun, crewFirstText } from "../../web/studio/crew_key.ts";
3333 import { agentsLine } from "../../web/studio/client_home.ts";
3434 import { lastVisit } from "../../core/home_visit.ts";
3535 import { quietFor, quietText } from "../../web/studio/home_empty.ts";
36 import { firstWeekText } from "../../web/first_week.ts";
3637 import { startedFromText } from "../../web/started_from.ts";
3738 import { sinceDigest } from "../../web/studio/since.ts";
3839 import { askForSomething } from "./tell.ts";
@@ -273,6 +274,8 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
273274 * template or a guest.
274275 */
275276 let startedFrom: string | null = null;
277 /** The first week's three steps as one line (`core/first_week.ts`); null when none are due. */
278 let firstWeek: string | null = null;
276279 /**
277280 * One line per fired flow alarm; an admin reads every repository, anyone else public ones alone.
278281 */
@@ -432,6 +435,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
432435 // this is a list of decisions — never a status that would be stale.
433436 pins = f.user ? listPins(f.db, f.user.id) : [];
434437 startedFrom = f.user === undefined ? null : startedFromText(f.app.config.dataDir);
438 firstWeek = firstWeekText(f.db, f.user);
435439 pinned = f.user ? pinnedRepoIds(f.db, f.user.id) : new Set<string>();
436440 all = listReposVisibleTo(f.db, f.user, { limit: 200 });
437441 found = undefined;
@@ -1180,6 +1184,11 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
11801184 // A site admin's forge strip, as the board's: "All fine" or a line
11811185 // per cause. Anyone else gets no rows and no reads.
11821186 let body = area;
1187 if (firstWeek !== null) {
1188 const [strip, rest] = split(body, "v", [len(1), fill(1)]);
1189 s.text(strip!.x, strip!.y, truncate(firstWeek, strip!.w), style(c.mutedFg, c.bg), strip!.x + strip!.w);
1190 body = rest!;
1191 }
11831192 if (startedFrom !== null) {
11841193 const [strip, rest] = split(body, "v", [len(1), fill(1)]);
11851194 s.text(strip!.x, strip!.y, truncate(startedFrom, strip!.w), style(c.mutedFg, c.bg), strip!.x + strip!.w);
src/web/first_week.ts added +27
@@ -0,0 +1,27 @@
1 /**
2 * The first week's three steps as plain links, a done one struck and named done for a screen
3 * reader; the home line of DESIGN.md's worked example (`<p class="small muted">` of `<a>`s), inside
4 * a labelled `<nav>`. See `core/first_week.ts`.
5 */
6
7 import type { Database } from "bun:sqlite";
8 import { firstWeekSteps, type FirstWeekStep } from "../core/first_week.ts";
9 import type { User } from "../core/users.ts";
10 import { html, type Html } from "./html.ts";
outdated

Principle 8 and accessibility: <s> alone does not tell a screen reader the step is done. Add a visually hidden ' (done)'. Also this nav is bespoke markup; use a named DESIGN.md component.

outdated

Still open: <s> carries no meaning for a screen reader. Render <s>Name an app</s><span class="sr-only"> (done)</span> (the repo visually-hidden class), and add a test asserting it. Also move the markup onto a named component from docs/DESIGN.md.

11
12 export function firstWeekHtml(steps: readonly FirstWeekStep[]): Html {
13 return html`<nav id="first-week" aria-label="First steps"><p class="small muted"><b>To start:</b>
14 ${steps.map((s) => html`<a href="${s.href}" data-step="${s.key}" data-done="${s.done ? "yes" : "no"}">${s.done ? html`<s>${s.text}</s><span class="sr-only"> (done)</span>` : html`${s.text}`}</a> `)}
15 </p></nav>`;
16 }
17
18 export function firstWeekBlock(db: Database, user: User | undefined): Html | null {
19 const steps = firstWeekSteps(db, user);
20 return steps === null ? null : firstWeekHtml(steps);
21 }
22
23 /** The same, as plain words for the terminal home. */
24 export function firstWeekText(db: Database, user: User | undefined): string | null {
25 const steps = firstWeekSteps(db, user);
26 return steps === null ? null : `To start: ${steps.map((s) => (s.done ? `✓ ${s.text}` : s.text)).join(" · ")}`;
27 }
src/web/pages/home_flow.ts +2
@@ -73,6 +73,7 @@ import { untoldAnswer, markTold } from "../../core/requests.ts";
7373 import { YOURE_IN_MESSAGE } from "../../actions/users.ts";
7474 import { spawnedForge } from "../../spawn/claim.ts";
7575 import { startedFromLine } from "../started_from.ts";
76 import { firstWeekBlock } from "../first_week.ts";
7677
7778
7879 /**
@@ -572,6 +573,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited
572573 const allowed = untoldAnswer(ctx.app.db, user.id) === "allowed";
573574 if (allowed) markTold(ctx.app.db, user.id, new Date().toISOString());
574575 const before = html`${allowed ? html`<div class="toast" data-tone="success" role="status" id="youre-in"><strong>${YOURE_IN_MESSAGE}</strong> Your account is open: tell the crew what you want to build.</div>` : null}
576 ${spawned === undefined ? firstWeekBlock(ctx.app.db, user) : null}
575577 <div class="hf-tell">${tellBox(ctx, user)}</div>`;
576578 // A client who asked for the whole home (`?all=1`) has a way back to their apps.
577579 const after = html`${ctx.url.searchParams.has("all") ? html`<p class="small muted" id="lean-home"><a href="/">Just my apps</a></p>` : null}${requestsCard(ctx, "home")}${timePhase(ctx.request, "held", () => heldLine(ctx, user))}
test/first-week.test.ts added +96
@@ -0,0 +1,96 @@
1 /**
2 * A new forge's home shows three first steps, struck as done, and none after a week or when all are
3 * done.
4 */
5 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
6 import { mkdtemp } 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 { createRepo } from "../src/actions/repos.ts";
11 import { mintInvite } from "../src/core/invites.ts";
12 import { createUser, type User } from "../src/core/users.ts";
13 import { firstWeekSteps, FIRST_WEEK_MS } from "../src/core/first_week.ts";
14 import { firstWeekBlock, firstWeekText } from "../src/web/first_week.ts";
15 import { serve } from "../src/http/server.ts";
16 import { createSession } from "../src/core/sessions.ts";
17 import { quietLogs } from "./helpers/globals.ts";
18
19 quietLogs();
20
21 describe("first week", () => {
22 let app: App;
23 let alice: User;
24 const done = () => Object.fromEntries((firstWeekSteps(app.db, alice) ?? []).map((s) => [s.key, s.done]));
25
26 beforeAll(async () => {
27 app = createApp({ dataDir: await mkdtemp(join(tmpdir(), "forge-first-week-")), port: 0 });
28 const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
29 if (!a.ok) throw new Error("user");
30 alice = a.value;
31 });
32 afterAll(() => app.db.close());
33
34 test("three links, none done, on a new forge", () => {
35 expect(done()).toEqual({ app: false, tell: false, invite: false });
36 const out = firstWeekBlock(app.db, alice)?.toString() ?? "";
37 expect(out).toContain("Name an app");
38 expect(out).toContain("Tell the crew something");
39 expect(out).toContain("Invite someone");
40 expect(out).not.toContain("<s>");
41 expect(firstWeekText(app.db, alice)).toContain("To start:");
42 });
43
44 test("naming an app strikes the first step", async () => {
45 const r = await createRepo(app, alice, { name: "menu", visibility: "private", description: "" });
46 if (!r.ok) throw new Error("repo");
47 expect(done()).toEqual({ app: true, tell: false, invite: false });
48 expect(firstWeekBlock(app.db, alice)?.toString()).toContain("<s>Name an app</s>");
49 });
50
51 test("a done step is named done for a screen reader, an open one is not", () => {
52 const out = firstWeekBlock(app.db, alice)?.toString() ?? "";
53 expect(out).toContain('<s>Name an app</s><span class="sr-only"> (done)</span>');
54 expect(out.match(/\(done\)/g)?.length).toBe(1);
55 expect(out).toContain('<p class="small muted">');
56 });
57
58 test("telling the crew strikes the second step", () => {
59 const repo = app.db.query<{ id: string }, []>("SELECT id FROM repo LIMIT 1").get()!;
60 app.db.run(
61 "INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, created_at, updated_at) VALUES ('i1', ?1, 1, 'issue', 'a menu', '', ?2, ?3, ?3)",
62 [repo.id, alice.id, new Date().toISOString()],
63 );
64 expect(done()).toEqual({ app: true, tell: true, invite: false });
65 });
66
67 test("an invite strikes the third, and with all three done the block is gone", () => {
68 mintInvite(app.db, alice.id, 7);
69 expect(firstWeekSteps(app.db, alice)).toBeNull();
70 expect(firstWeekBlock(app.db, alice)).toBeNull();
71 });
72
73 test("nothing for a forge a week old, a guest or a non-admin", async () => {
74 const bob = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
75 if (!bob.ok) throw new Error("user");
76 expect(firstWeekSteps(app.db, bob.value)).toBeNull();
77 expect(firstWeekSteps(app.db, undefined)).toBeNull();
78 app.db.run("DELETE FROM invite");
79 expect(firstWeekSteps(app.db, alice)).not.toBeNull();
80 expect(firstWeekSteps(app.db, alice, Date.now() + FIRST_WEEK_MS + 1000)).toBeNull();
81 });
82
83 test("the home page carries the line, with the done step struck", async () => {
84 const servers = await serve(app);
85 try {
86 const session = createSession(app.db, alice.id);
87 const res = await fetch(`${servers.url}/`, { headers: { cookie: `forge_session=${session.token}` } });
88 const page = await res.text();
89 expect(page).toContain('id="first-week"');
90 expect(page).toContain("<s>Name an app</s>");
91 expect(page).toContain('data-step="invite" data-done="no"');
92 } finally {
93 servers.stop();
94 }
95 });
96 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs