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

A client list row for a forge link shows sent, opened and first-ask times, each from a recorded event #13704

Merged opened this

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

Merged

scout/forge:scout/13682-a-client-list-row-for-a-forge-link-shows → main 5 commits fork

  • Merged. scout/13682-a-client-list-row-for-a-forge-link-shows was merged into main as cea5a5e.

Review

Sign in to review this change.
10 files changed +191 −33
docs/features/README.md +1
@@ -316,6 +316,7 @@ Read with the guide page [Hosting forges for others, and getting paid](../guide-
316316 - [A child forge's own filesystem](child-filesystem.md)
317317 - [A client's monthly bill](forge-bill.md)
318318 - [A forge for a client, from one link](client-forge.md)
319 - [The client list's three times: sent, opened, first tell](client-link-times.md)
319320 - [A forge whose billing is none](lapsed-forge.md)
320321 - [A forge's claim link as a QR in the terminal](forge-link-qr.md)
321322 - [A forge's own key and budgets](own-forge-budgets.md)
src/core/next-steps.ts +20 −8
@@ -26,14 +26,20 @@ export interface NextStep {
2626
2727 const STEP_KEYS: readonly StepKey[] = ["everyday", "apps", "tell"];
2828
29 /** The three steps' words, the one source for the first-login card and the client list's line about it. */
29 /**
30 * The three steps' words, the one source for the first-login card and the client list's line about
31 * it.
32 */
3033 export const STEP_TITLES: Record<StepKey, string> = {
3134 everyday: "Make your everyday account",
3235 apps: "Open your apps",
3336 tell: "Tell the crew something",
3437 };
3538
36 /** What the recipient of a sent forge sees first, in one line: the apps chosen, that the crew is working, the three steps. */
39 /**
40 * What the recipient of a sent forge sees first, in one line: the apps chosen, that the crew is
41 * working, the three steps.
42 */
3743 export function firstScreenLine(apps: readonly string[]): string {
3844 const chosen = apps.length === 0 ? "the apps you pick" : apps.join(", ");
3945 return `They will see ${chosen}, their crew working, and three next steps: ${STEP_KEYS.map((k) => STEP_TITLES[k]).join("; ")}.`;
@@ -41,7 +47,10 @@ export function firstScreenLine(apps: readonly string[]): string {
4147
4248 const OPENED_APP = "first_step_opened_app";
4349
44 /** The admin whose forge this is, as seen by `user`: themselves, or the admin of their everyday account. */
50 /**
51 * The admin whose forge this is, as seen by `user`: themselves, or the admin of their everyday
52 * account.
53 */
4554 function ownerFor(app: App, user: User): User | undefined {
4655 if (user.kind !== "user") return undefined;
4756 if (user.isAdmin) return user;
@@ -93,19 +102,19 @@ export async function nextStepsFor(
93102 * have an everyday account (or chose to keep working as admin), and when
94103 * they last told the crew something (null before the first tell).
95104 */
96 export function progress(app: App): { claimed: boolean; everyday: boolean; lastTellAt: string | null } {
105 export function progress(app: App): { claimed: boolean; everyday: boolean; lastTellAt: string | null; firstTellAt: string | null } {
97106 const owner = app.db
98107 .query<{ id: string }, []>(
99108 "SELECT id FROM user WHERE is_admin = 1 AND is_agent = 0 AND kind = 'user' ORDER BY created_at LIMIT 1",
100109 )
101110 .get();
102111 const admin = owner === null ? undefined : getUserById(app.db, owner.id);
103 if (admin === undefined) return { claimed: false, everyday: false, lastTellAt: null };
112 if (admin === undefined) return { claimed: false, everyday: false, lastTellAt: null, firstTellAt: null };
104113 const daily = everydayOf(app.db, admin);
105114 const people = [admin.id, ...(daily ? [daily.id] : [])];
106115 const last = app.db
107 .query<{ at: string | null }, string[]>(
108 `SELECT MAX(i.created_at) AS at FROM issue i
116 .query<{ at: string | null; first: string | null }, string[]>(
117 `SELECT MAX(i.created_at) AS at, MIN(i.created_at) AS first FROM issue i
109118 WHERE i.kind = 'issue' AND i.author_id IN (${people.map((_, n) => `?${n + 1}`).join(",")})
110119 AND i.id NOT IN (SELECT direction_issue_id FROM repo WHERE direction_issue_id IS NOT NULL)`,
111120 )
@@ -114,10 +123,13 @@ export function progress(app: App): { claimed: boolean; everyday: boolean; lastT
114123 claimed: true,
115124 everyday: daily !== undefined || keptAdmin(app.db, admin),
116125 lastTellAt: last?.at ?? null,
126 firstTellAt: last?.first ?? null,
117127 };
118128 }
119129
120 /** The owner (or their everyday account) opened an app on a spawned forge: the second step is done. */
130 /**
131 * The owner (or their everyday account) opened an app on a spawned forge: the second step is done.
132 */
121133 export async function noteAppOpened(app: App, user: User | undefined): Promise<void> {
122134 if (!user) return;
123135 const owner = ownerFor(app, user);
src/spawn/clients.ts +13 −3
@@ -64,6 +64,8 @@ export interface ClientRow {
6464 */
6565 readonly appLinks?: readonly AppLinkLine[];
6666 readonly sentAt: string | null;
67 /** When its person first told the crew something, from its last beat; null until then. */
68 readonly firstTellAt?: string | null | undefined;
6769 /** False while the child is still being made (a resumed spawn finishes it). */
6870 readonly made: boolean;
6971 readonly claimed: boolean | null;
@@ -337,6 +339,8 @@ export async function clientRows(app: App, options: { probe?: boolean } = {}): P
337339 apps: c.apps,
338340 appLinks: links[i] ?? [],
339341 sentAt: c.createdAt,
342 // Undefined until the child has beaten with the field: unknown is not "not yet".
343 firstTellAt: beats[i]?.beat.firstTellAt,
340344 made: c.done,
341345 claimed: states[i]?.claimed ?? null,
342346 lastActivityAt: people[i]?.lastAt ?? null,
@@ -618,6 +622,10 @@ export interface Seen {
618622 readonly openedAt: string | null;
619623 /** ISO of a person's last action there; null until they signed in. */
620624 readonly lastSeenAt: string | null;
625 /**
626 * ISO of the first tell there, from a recorded issue; null until the person has told the crew.
627 */
628 readonly firstTellAt?: string | null | undefined;
621629 /**
622630 * ISO of the last "send again", which ended the earlier link; null once claimed or when never.
623631 */
@@ -625,17 +633,19 @@ export interface Seen {
625633 }
626634
627635 /** Null while the forge is still being made or did not answer: nothing is claimed unknown. */
628 export function seenOf(r: Pick<ClientRow, "made" | "claimed" | "sentAt" | "link" | "lastActivityAt" | "replacedAt">): Seen | null {
636 export function seenOf(r: Pick<ClientRow, "made" | "claimed" | "sentAt" | "firstTellAt" | "link" | "lastActivityAt" | "replacedAt">): Seen | null {
629637 if (!r.made || r.claimed === null || r.link === null) return null;
630638 const openedAt = r.link.openedAt ?? null;
631 return { sentAt: r.sentAt, opened: openedAt !== null || r.link.usedAt != null || r.link.state === "used", openedAt, lastSeenAt: r.claimed ? r.lastActivityAt : null, replacedAt: r.claimed ? null : r.replacedAt ?? null };
639 return { sentAt: r.sentAt, opened: openedAt !== null || r.link.usedAt != null || r.link.state === "used", openedAt, lastSeenAt: r.claimed ? r.lastActivityAt : null, firstTellAt: r.firstTellAt, replacedAt: r.claimed ? null : r.replacedAt ?? null };
632640 }
633641
634642 /** The one line as parts to join with " · ": the words, and the instant to say beside them. */
635643 export function seenParts(s: Seen): { words: string; at: string | null }[] {
636644 return [
637645 ...(s.sentAt === null ? [] : [{ words: "sent", at: s.sentAt }]),
638 s.opened ? { words: s.openedAt === null ? "opened (time not noted)" : "opened", at: s.openedAt } : { words: "not opened yet", at: null },
646 s.opened ? { words: s.openedAt === null ? "opened (time not noted)" : "opened", at: s.openedAt } : { words: "opened: not yet", at: null },
647 // Nothing while unknown (undefined); "not yet" only once the child has said there is none.
648 ...(s.firstTellAt === undefined ? [] : [s.firstTellAt === null ? { words: "first tell: not yet", at: null } : { words: "first tell", at: s.firstTellAt }]),
639649 ...(s.replacedAt == null ? [] : [{ words: "link replaced", at: s.replacedAt }]),
640650 ...(s.lastSeenAt === null ? [] : [{ words: "last seen", at: s.lastSeenAt }]),
641651 ];
src/spawn/heartbeat.ts +42 −12
@@ -52,19 +52,30 @@ export interface Beat {
5252 readonly version: string;
5353 readonly openProposals: number;
5454 readonly children: number;
55 /** The tip of the child's own forge code; absent from an older child, null when it carries none. */
55 /**
56 * The tip of the child's own forge code; absent from an older child, null when it carries none.
57 */
5658 readonly forgeTip?: string | null;
5759 /** When the child cut its upstream link; null while it follows. */
5860 readonly severedAt?: string | null;
5961 /** How the child follows its parent's code (`parent.json`); absent from an older child. */
6062 readonly mode?: FollowMode;
61 /** Commits behind the parent's code (`upstream.json`); null when unknown, absent from an older child. */
63 /**
64 * Commits behind the parent's code (`upstream.json`); null when unknown, absent from an older
65 * child.
66 */
6267 readonly upstreamBehind?: number | null;
6368 /** True while a converge issue is open on the child; absent from an older child. */
6469 readonly conflict?: boolean;
65 /** Dollars the child's crew spent since 00:00 UTC; absent from an older child or when it sent a bad value. */
70 /**
71 * Dollars the child's crew spent since 00:00 UTC; absent from an older child or when it sent a
72 * bad value.
73 */
6674 readonly spendTodayUsd?: number;
67 /** The child's forge cap in dollars (the daily ceiling that pauses its crew), null when it has none; absent when unsaid or bad. */
75 /**
76 * The child's forge cap in dollars (the daily ceiling that pauses its crew), null when it has
77 * none; absent when unsaid or bad.
78 */
6879 readonly ceilingUsd?: number | null;
6980 /** Why its crew cannot start ("no_model_key" today); absent when it can or from an old child. */
7081 readonly crewHeld?: typeof NO_KEY_HELD;
@@ -74,6 +85,8 @@ export interface Beat {
7485 readonly everyday?: boolean;
7586 /** When its person last told the crew something; null before the first, absent likewise. */
7687 readonly lastTellAt?: string | null;
88 /** When its person first told the crew something; null before the first, absent likewise. */
89 readonly firstTellAt?: string | null;
7790 /**
7891 * When a stranger last asked this forge's sender for a new forge link, and when that link expired
7992 * (ISO); absent when none.
@@ -83,7 +96,7 @@ export interface Beat {
8396 }
8497
8598 const OPTIONAL = new Set([
86 "forgeTip", "severedAt", "mode", "upstreamBehind", "conflict", "spendTodayUsd", "ceilingUsd", "crewHeld", "claimed", "everyday", "lastTellAt", "linkAskedAt", "linkExpiredAt",
99 "forgeTip", "severedAt", "mode", "upstreamBehind", "conflict", "spendTodayUsd", "ceilingUsd", "crewHeld", "claimed", "everyday", "lastTellAt", "firstTellAt", "linkAskedAt", "linkExpiredAt",
87100 ]);
88101 const USD_MAX = 1_000_000;
89102
@@ -133,9 +146,13 @@ export function parseBeat(raw: string): Beat | undefined {
133146 const claimed = d["claimed"];
134147 const everyday = d["everyday"];
135148 const told = d["lastTellAt"];
149 const first = d["firstTellAt"];
150 const firstOk =
151 first === null || (typeof first === "string" && ISO_TIME.test(first) && !Number.isNaN(Date.parse(first)));
136152 const claimedOk = typeof claimed === "boolean";
137153 const everydayOk = typeof everyday === "boolean";
138 // Strict ISO: it is printed into the parent admin's terminal, so nothing but digits and punctuation.
154 // Strict ISO: it is printed into the parent admin's terminal, so nothing but digits and
155 // punctuation.
139156 const toldOk =
140157 told === null || (typeof told === "string" && ISO_TIME.test(told) && !Number.isNaN(Date.parse(told)));
141158 // Both or neither, strict ISO: they become words on the sender's page.
@@ -168,6 +185,7 @@ export function parseBeat(raw: string): Beat | undefined {
168185 ...(claimedOk ? { claimed } : {}),
169186 ...(everydayOk ? { everyday } : {}),
170187 ...(told !== undefined && toldOk ? { lastTellAt: told as string | null } : {}),
188 ...(first !== undefined && firstOk ? { firstTellAt: first as string | null } : {}),
171189 ...(askedAt === undefined ? {} : { linkAskedAt: askedAt as string, linkExpiredAt: expiredAt as string }),
172190 };
173191 }
@@ -258,7 +276,8 @@ async function takeBeat(
258276
259277 /**
260278 * A child's stranger asked for a new forge link: one note, for the account that made the child,
261 * once per ask (a beat is repeated every ten minutes) and at most one an hour per child. It names the forge and when the link ended.
279 * once per ask (a beat is repeated every ten minutes) and at most one an hour per child. It names
280 * the forge and when the link ended.
262281 */
263282 async function noteTheAsk(app: App, name: string, asked: string, expired: string): Promise<void> {
264283 const { childNamed } = await import("../actions/spawn.ts");
@@ -320,7 +339,9 @@ export function standing(app: App, name: string, at = Date.now()): Beat {
320339 };
321340 }
322341
323 /** What the crew spent today, and the daily ceiling that pauses it (null when the forge sets none). */
342 /**
343 * What the crew spent today, and the daily ceiling that pauses it (null when the forge sets none).
344 */
324345 export function spendReport(app: App, now = new Date()): { spendTodayUsd: number; ceilingUsd: number | null } {
325346 const cap = forgeCeiling(app.config);
326347 return {
@@ -329,7 +350,9 @@ export function spendReport(app: App, now = new Date()): { spendTodayUsd: number
329350 };
330351 }
331352
332 /** What a fork says of how it follows: its tip, whether it cut the link, and how far behind it is. */
353 /**
354 * What a fork says of how it follows: its tip, whether it cut the link, and how far behind it is.
355 */
333356 async function forkReport(app: App, forge: ForgeLink) {
334357 const up = await upstreamState(app);
335358 const behind = up?.behind ?? null;
@@ -342,7 +365,10 @@ async function forkReport(app: App, forge: ForgeLink) {
342365 };
343366 }
344367
345 /** In a cell the parent's public address is out of reach; its relayed loopback port (`FORGE_PARENT_LOCAL`) is not. */
368 /**
369 * In a cell the parent's public address is out of reach; its relayed loopback port
370 * (`FORGE_PARENT_LOCAL`) is not.
371 */
346372 export function beatBase(upstream: string): string {
347373 const local = process.env["FORGE_PARENT_LOCAL"] ?? "";
348374 return isParentLocal(local) ? local : upstream;
@@ -351,7 +377,10 @@ export function beatBase(upstream: string): string {
351377 type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
352378 let lastAt = 0;
353379
354 /** A spawned child's one report to its parent; false when it has no parent or the try failed. Never throws. */
380 /**
381 * A spawned child's one report to its parent; false when it has no parent or the try failed. Never
382 * throws.
383 */
355384 export async function sendBeat(
356385 app: App,
357386 fetcher: FetchLike = fetch,
@@ -389,7 +418,8 @@ export async function sendBeat(
389418 const said = (await res.json().catch(() => undefined)) as { follow?: unknown } | undefined;
390419 const { hearLandings, parseHints } = await import("./app_follow.ts");
391420 await hearLandings(app, parseHints(said?.follow)).catch(() => {});
392 // What this forge asked its host to let it reach is looked at with every beat, so an answer is heard with no page open (`actions/ask_host.ts`).
421 // What this forge asked its host to let it reach is looked at with every beat, so an answer
422 // is heard with no page open (`actions/ask_host.ts`).
393423 const { refreshAsks } = await import("../actions/ask_host.ts");
394424 await refreshAsks(app);
395425 }
test/client-list-events.test.ts added +82
@@ -0,0 +1,82 @@
1 /**
2 * The client list's three times for a link (#13682): sent, opened, first tell. Opened is the
3 * child's once-written claim note; first tell is the earliest issue its person wrote, carried on
4 * the heartbeat. An empty one says "not yet".
5 */
6 import { describe, expect, test } from "bun:test";
7 import { mkdtempSync } from "node:fs";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp } from "../src/app.ts";
11 import { progress } from "../src/core/next-steps.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import { createUser } from "../src/core/users.ts";
14 import { parseBeat } from "../src/spawn/heartbeat.ts";
15 import { mintClaim, noteOpened, linkOf } from "../src/spawn/claim.ts";
16 import { createOrg } from "../src/core/orgs.ts";
17 import { seenOf, seenParts, type ClientRow } from "../src/spawn/clients.ts";
18 import { quietLogs } from "./helpers/globals.ts";
19
20 quietLogs();
21
22 const row = (over: Record<string, unknown>) =>
23 ({ made: true, claimed: true, sentAt: "2026-11-01T00:00:00.000Z", lastActivityAt: null, replacedAt: null,
24 link: { state: "used", revokedAt: null, usedAt: null, openedAt: null }, ...over }) as unknown as ClientRow;
25 const words = (r: ClientRow) => seenParts(seenOf(r)!).map((p) => `${p.words}${p.at ? " " + p.at : ""}`);
26
27 describe("the client list's three times", () => {
28 test("empty ones say not yet", () => {
29 const w = words(row({ claimed: false, firstTellAt: null, link: { state: "open", revokedAt: null, usedAt: null, openedAt: null } }));
30 expect(w).toEqual(["sent 2026-11-01T00:00:00.000Z", "opened: not yet", "first tell: not yet"]);
31 });
32
33 test("a first tell not yet reported says nothing, not \"not yet\"", () => {
34 expect(words(row({ claimed: false, link: { state: "open", revokedAt: null, usedAt: null, openedAt: null } })).join("|")).not.toContain("first tell");
35 });
36
37 test("each shows its recorded time", () => {
38 const w = words(row({ firstTellAt: "2026-11-03T00:00:00.000Z", link: { state: "used", revokedAt: null, usedAt: null, openedAt: "2026-11-02T00:00:00.000Z" } }));
39 expect(w).toContain("opened 2026-11-02T00:00:00.000Z");
40 expect(w).toContain("first tell 2026-11-03T00:00:00.000Z");
41 });
42
43 test("opening writes once", async () => {
44 const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "cle-")) });
45 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
46 if (!u.ok) throw new Error(u.error);
47 const org = createOrg(app.db, "kin", u.value.id);
48 if (!org.ok) throw new Error(org.error);
49 mintClaim(app.db, org.value.id);
50 expect(noteOpened(app.db, Date.now())).toBe(true);
51 const first = linkOf(app.db)!.openedAt;
52 expect(first).not.toBeNull();
53 expect(noteOpened(app.db, Date.now() + 5000)).toBe(false);
54 expect(linkOf(app.db)!.openedAt).toBe(first);
55 app.close();
56 });
57
58 test("a first tell is the earliest issue and does not move with later ones", async () => {
59 const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "cle-")) });
60 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
61 if (!u.ok) throw new Error(u.error);
62 expect(progress(app).firstTellAt).toBeNull();
63 const repo = await createRepo(app, u.value, { name: "bakery" });
64 if (!repo.ok) throw new Error("repo");
65 const put = (n: number, at: string) =>
66 app.db
67 .query("INSERT INTO issue (id, repo_id, number, title, author_id, created_at) VALUES (?1, ?2, ?3, 'hi', ?4, ?5)")
68 .run(`t${n}`, repo.value.id, 9000 + n, u.value.id, at);
69 put(1, "2030-02-03T04:05:06.000Z");
70 put(2, "2030-03-03T04:05:06.000Z");
71 expect(progress(app)).toMatchObject({ firstTellAt: "2030-02-03T04:05:06.000Z", lastTellAt: "2030-03-03T04:05:06.000Z" });
72 app.close();
73 });
74
75 test("the beat carries first tell only when it is a time", () => {
76 const beat = (o: Record<string, unknown>) => parseBeat(JSON.stringify({ name: "maria", at: 1, version: "1.0.0", openProposals: 0, children: 0, ...o }));
77 expect(beat({ firstTellAt: "2030-01-01T00:00:00Z" })?.firstTellAt).toBe("2030-01-01T00:00:00Z");
78 expect(beat({ firstTellAt: null })?.firstTellAt).toBeNull();
79 expect(beat({ firstTellAt: "soon" })?.firstTellAt).toBeUndefined();
80 expect(beat({ firstTellAt: "soon" })?.name).toBe("maria");
81 });
82 });
test/client-list.test.ts +9
@@ -313,8 +313,15 @@ describe("the client list", () => {
313313 return JSON.parse(tool.result.content[0].text).forges.find((f: any) => f.name === "maria").nextStep;
314314 };
315315 // The claim made the child's person an admin; nothing else yet.
316 // clientRows copies the beat's firstTellAt onto the row: none told yet reads "not yet".
317 const seen = async () => {
318 const html = (await (await list(admin)).text()).replace(/\s+/g, " ");
319 const at = html.indexOf('data-forge="maria"');
320 return /first tell[^<]*/.exec(html.slice(at, html.indexOf("</li>", at)))?.[0];
321 };
316322 expect(await beatTo()).toBe(true);
317323 expect(await words()).toBe("no everyday account yet");
324 expect(await seen()).toContain("first tell: not yet");
318325 expect((await mariaStep()).words).toBe("no everyday account yet");
319326 const person = child.db.query<{ id: string }, []>("SELECT id FROM user WHERE is_admin = 1 AND kind = 'user' AND is_agent = 0").get()!;
320327 keepAdmin(child.db, getUserById(child.db, person.id)!);
@@ -327,6 +334,8 @@ describe("the client list", () => {
327334 .run(repo.id, person.id);
328335 expect(await beatTo()).toBe(true);
329336 expect(await words()).toBe("going: last tell");
337 expect(await seen()).toMatch(/^first tell\s*(?!: not yet)/);
338 expect(await seen()).not.toContain("not yet");
330339 const step = await mariaStep();
331340 expect(step).toMatchObject({ key: "going", lastTellAt: "2030-02-03T04:05:06.000Z" });
332341 expect(step.words).toBe("going: last tell 2030-02-03T04:05:06.000Z");
test/family-heartbeat.test.ts +1
@@ -354,6 +354,7 @@ describe("family heartbeats", () => {
354354 "claimed",
355355 "crewHeld",
356356 "everyday",
357 "firstTellAt",
357358 "lastTellAt",
358359 "name",
359360 "openProposals",
test/mcp-clients.test.ts +1 −1
@@ -56,7 +56,7 @@ test("the owner reads each client in the page's words", async () => {
5656 expect(c[0].name).toBe("alpha");
5757 expect(c[0].for).toBe("Ann");
5858 expect(c[0].claimed).toBe("Not claimed yet");
59 expect(c[0].seen).toContain("not opened yet");
59 expect(c[0].seen).toContain("opened: not yet");
6060 });
6161
6262 test("anyone else gets the usual refusal", async () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs