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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13460-a-new-forge-s-first-login-shows-three-ne → main 7 commits fork 2 threads · 2 unresolved
9 files
changed +199
−6
docs/design/attention-budget.json +6 −5
| @@ -1,15 +1,16 @@ | ||
| 1 | 1 | { |
| 2 | 2 | "home": { |
| 3 | 3 | "390": { |
| 4 | "words": 286, | |
| 5 | "blocks": 49, | |
| 4 | "words": 297, | |
| 5 | "blocks": 50, | |
| 6 | 6 | "colours": 7 |
| 7 | 7 | }, |
| 8 | 8 | "1280": { |
| 9 | "words": 286, | |
| 10 | "blocks": 49, | |
| 9 | "words": 297, | |
| 10 | "blocks": 50, | |
| 11 | 11 | "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)." | |
| 13 | 14 | }, |
| 14 | 15 | "repository": { |
| 15 | 16 | "390": { |
docs/features/README.md +1
| @@ -17,6 +17,7 @@ A new note gets a row here (`test/feature-orphans.test.ts`). | ||
| 17 | 17 | Read with the guide page [](../guide-what-a-forge-is.md). |
| 18 | 18 | |
| 19 | 19 | - [](started-from.md) |
| 20 | - [](first-week.md) | |
| 20 | 21 | - [](template-timing.md) |
| 21 | 22 | - [](feed-look.md) |
| 22 | 23 | - [](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; | ||
| 16 | 16 | /** At most this many watchers at once per forge; a spawn past it is made but not timed. */ |
| 17 | 17 | export const MAX_WATCHERS = 20; |
| 18 | 18 | 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 | */ | |
| 20 | 23 | export const GIVE_UP_MS = 10 * 60_000; |
| 21 | 24 | |
| 22 | 25 | export type Probe = () => Promise<boolean>; |
src/tui/screens/dashboard.ts +9
| @@ -33,6 +33,7 @@ import { crewCanRun, crewFirstText } from "../../web/studio/crew_key.ts"; | ||
| 33 | 33 | import { agentsLine } from "../../web/studio/client_home.ts"; |
| 34 | 34 | import { lastVisit } from "../../core/home_visit.ts"; |
| 35 | 35 | import { quietFor, quietText } from "../../web/studio/home_empty.ts"; |
| 36 | import { firstWeekText } from "../../web/first_week.ts"; | |
| 36 | 37 | import { startedFromText } from "../../web/started_from.ts"; |
| 37 | 38 | import { sinceDigest } from "../../web/studio/since.ts"; |
| 38 | 39 | import { askForSomething } from "./tell.ts"; |
| @@ -273,6 +274,8 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 273 | 274 | * template or a guest. |
| 274 | 275 | */ |
| 275 | 276 | 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; | |
| 276 | 279 | /** |
| 277 | 280 | * One line per fired flow alarm; an admin reads every repository, anyone else public ones alone. |
| 278 | 281 | */ |
| @@ -432,6 +435,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 432 | 435 | // this is a list of decisions — never a status that would be stale. |
| 433 | 436 | pins = f.user ? listPins(f.db, f.user.id) : []; |
| 434 | 437 | startedFrom = f.user === undefined ? null : startedFromText(f.app.config.dataDir); |
| 438 | firstWeek = firstWeekText(f.db, f.user); | |
| 435 | 439 | pinned = f.user ? pinnedRepoIds(f.db, f.user.id) : new Set<string>(); |
| 436 | 440 | all = listReposVisibleTo(f.db, f.user, { limit: 200 }); |
| 437 | 441 | found = undefined; |
| @@ -1180,6 +1184,11 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 1180 | 1184 | // A site admin's forge strip, as the board's: "All fine" or a line |
| 1181 | 1185 | // per cause. Anyone else gets no rows and no reads. |
| 1182 | 1186 | 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 | } | |
| 1183 | 1192 | if (startedFrom !== null) { |
| 1184 | 1193 | const [strip, rest] = split(body, "v", [len(1), fill(1)]); |
| 1185 | 1194 | 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
Still open: |
||
| 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"; | ||
| 73 | 73 | import { YOURE_IN_MESSAGE } from "../../actions/users.ts"; |
| 74 | 74 | import { spawnedForge } from "../../spawn/claim.ts"; |
| 75 | 75 | import { startedFromLine } from "../started_from.ts"; |
| 76 | import { firstWeekBlock } from "../first_week.ts"; | |
| 76 | 77 | |
| 77 | 78 | |
| 78 | 79 | /** |
| @@ -572,6 +573,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited | ||
| 572 | 573 | const allowed = untoldAnswer(ctx.app.db, user.id) === "allowed"; |
| 573 | 574 | if (allowed) markTold(ctx.app.db, user.id, new Date().toISOString()); |
| 574 | 575 | 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} | |
| 575 | 577 | <div class="hf-tell">${tellBox(ctx, user)}</div>`; |
| 576 | 578 | // A client who asked for the whole home (`?all=1`) has a way back to their apps. |
| 577 | 579 | 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 | }); |
new above
offline
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.