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

A fork link's health shows on the flows view #13274

Merged opened this

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

Merged

scout/forge:scout/13256-a-fork-link-s-health-shows-on-the-flows → main 2 commits fork 1 thread · 1 unresolved

  • Merged. scout/13256-a-fork-link-s-health-shows-on-the-flows was merged into main as 0a10625.

Review

Sign in to review this change.
6 files changed +175 −21
docs/features/forge-origin.md +1 −1
@@ -54,7 +54,7 @@ One contract written for every shape a network takes: a follower, a fork, a mirr
5454
5555 **Where you meet it.** A fork's standing against its parent now names the one action that reconciles it (`none`, `fast-forward`, `offer`, `merge`, `keep-both`) and says it in words: in the `following` API read (`action`, `words`), on the fork's home card, in the terminal's forks screen (`Forks` → the follows row), and in MCP `following`. Taking the parent's work (`fastForwardFork`, which every push to the parent triggers) goes through `syncLink`, so it is compare-and-swap, stages the parent's tip at `refs/following/<branch>`, and refuses a divergence. `source` is always a repository path computed from rows, never text a person typed. Syncs into the same repository's stage ref take turns, so a push's follow-on and a person's click at once never race on that ref (test: "syncs at once into one stage ref take turns").
5656
57 `test/sync-shapes.test.ts` walks each shape with real git between bare repositories on one machine. `scripts/forge-compat-lab/shapes.ts` holds the same shapes as lab cells between two real forges, but **they have not run yet**: they run only when asked for (`LAB_ONLY=shapes scripts/forge-compat-lab.sh`) and are not proven until a docker host has walked them. Not shown either: that a sync at one door reaches a web viewer live (the card reads the standing on each load; nothing pushes it). Not yet wired: the flows-view health of each link, the schedule probe, and the crew taking the action on autonomous repositories (the rest of #9451).
57 `test/sync-shapes.test.ts` walks each shape with real git between bare repositories on one machine. `scripts/forge-compat-lab/shapes.ts` holds the same shapes as lab cells between two real forges, but **they have not run yet**: they run only when asked for (`LAB_ONLY=shapes scripts/forge-compat-lab.sh`) and are not proven until a docker host has walked them. Not shown either: that a sync at one door reaches a web viewer live (the card reads the standing on each load; nothing pushes it). Each fork's link to its parent wears one word on the flows view (`linkWord`, `src/flows/view.ts`): following, behind N, conflicted, severed, or quiet (not read lately, or taking but not taken within the period; never green). It reads the standing the card already kept, with no git and no polling (test: `test/flows-link-word.test.ts`). Not yet wired: the schedule probe, and the crew taking the action on autonomous repositories (the rest of #9451).
5858
5959 ## A downstream forge as a peer (#9451)
6060
src/core/following.ts +28 −6
@@ -57,7 +57,10 @@ export interface Following {
5757 readonly db: Database;
5858 readonly reposRoot: string;
5959 readonly bus: EventBus;
60 /** Who a merge the forge makes for a fork's owner is written as; absent, a fork never merges by itself. */
60 /**
61 * Who a merge the forge makes for a fork's owner is written as; absent, a fork never merges by
62 * itself.
63 */
6164 readonly authorOf?: (userId: string) => (MergeIdentity & { readonly id: string }) | undefined;
6265 }
6366
@@ -189,7 +192,10 @@ export interface ForkRelation {
189192 readonly conflicts: readonly string[];
190193 readonly forkTip: string;
191194 readonly parentTip: string;
192 /** The one action that reconciles the two, and the words for it: the sync contract's (`describeLink`). */
195 /**
196 * The one action that reconciles the two, and the words for it: the sync contract's
197 * (`describeLink`).
198 */
193199 readonly action: Reconcile;
194200 readonly words: string;
195201 }
@@ -254,13 +260,26 @@ export async function forkRelation(
254260 * on every tab says no number rather than a stale one (#12683). Never asks git.
255261 */
256262 export function keptBehind(forge: Pick<Following, "reposRoot">, fork: Repo, parent: Repo): number | undefined {
263 return keptStanding(forge, fork, parent)?.[1];
264 }
265
266 /**
267 * The whole standing `forkRelation` last counted, read the same way as `keptBehind`: no await, no
268 * git. Undefined when nothing has counted this pair of tips. A synced pair is
269 * `["synced", 0, 0, true, []]`.
270 */
271 export function keptStanding(
272 forge: Pick<Following, "reposRoot">,
273 fork: Repo,
274 parent: Repo,
275 ): Standing | undefined {
257276 const parentDir = repoDir(forge.reposRoot, parent.ownerName, parent.name);
258277 const forkDir = repoDir(forge.reposRoot, fork.ownerName, fork.name);
259278 const parentTip = readTipSync(parentDir, `refs/heads/${parent.defaultBranch}`);
260279 const forkTip = readTipSync(forkDir, `refs/heads/${fork.defaultBranch}`);
261280 if (parentTip === undefined || forkTip === undefined) return undefined;
262 if (parentTip === forkTip) return 0;
263 return relationCache.get(`${forkDir}\0${parentDir}\0${forkTip}\0${parentTip}`)?.[1];
281 if (parentTip === forkTip) return ["synced", 0, 0, true, []];
282 return relationCache.get(`${forkDir}\0${parentDir}\0${forkTip}\0${parentTip}`);
264283 }
265284
266285 /** Tips already asked for in one read, so a parent is read once for all its forks. */
@@ -284,7 +303,7 @@ function tipOf(
284303 return read;
285304 }
286305
287 type Standing = [
306 export type Standing = [
288307 RelationState,
289308 behind: number,
290309 ahead: number,
@@ -608,7 +627,10 @@ export interface LineageNode {
608627 readonly repo: Repo;
609628 /** Against this node's parent; absent on the root, and past the budget. */
610629 readonly relation: ForkRelation | undefined;
611 /** How it follows its parent, as stored (a fork that never chose has the default); absent on the root. */
630 /**
631 * How it follows its parent, as stored (a fork that never chose has the default); absent on the
632 * root.
633 */
612634 readonly mode?: ForkFollowMode;
613635 readonly children: readonly LineageNode[];
614636 }
src/flows/view.ts +53 −6
@@ -7,18 +7,55 @@
77
88 import type { Database } from "bun:sqlite";
99 import { getCursor } from "../core/origins.ts";
10 import { forkFollowMode } from "../core/fork_follow.ts";
10 import { forkFollowMode, lastTookAt } from "../core/fork_follow.ts";
1111 import { canAdmin, canRead, canWrite, getRepoById, repoDatesFor, visibleForks, type Repo } from "../core/repos.ts";
1212 import type { User } from "../core/users.ts";
1313 import { aheadWords, parseAhead } from "../origins/ahead.ts";
14 import { keptStanding } from "../core/following.ts";
1415 import { counts, lastScanAt } from "../checks/scan_store.ts";
1516
16 /** A followed link is stale when its last head comparison is older than this (three follow periods). */
17 /**
18 * A followed link is stale when its last head comparison is older than this (three follow periods).
19 */
1720 export const STALE_MS = 3 * 30 * 60_000;
1821
19 /** How a link stands: `ok` level, `behind` has news, `diverged` both moved, `unread` could not be read, `stale` not read lately, `off` not following, `none` nothing to compare. */
22 /**
23 * How a link stands: `ok` level, `behind` has news, `diverged` both moved, `unread` could not be
24 * read, `stale` not read lately, `off` not following, `none` nothing to compare.
25 */
2026 export type Health = "ok" | "behind" | "diverged" | "unread" | "stale" | "off" | "none";
2127
28 /** The one word a fork's upstream link wears on the flows view. */
29 export type LinkWord = "following" | "behind" | "conflicted" | "severed" | "quiet";
30
31 /**
32 * A fork's link to its parent, from the standing already kept (no git, no polling). `standing` is
33 * undefined when nothing has counted the two tips lately, and a link nobody has read is `quiet`,
34 * never green; so is a taking fork that is behind and has not taken within the period.
35 */
36 export function linkWord(
37 mode: string,
38 standing: readonly [string, number, number, boolean, readonly string[]] | undefined,
39 tookAt: string | null,
40 now: number,
41 ): { word: LinkWord; behind: number } {
42 if (mode === "dont-follow") return { word: "severed", behind: 0 };
43 if (standing === undefined) return { word: "quiet", behind: 0 };
44 const [state, behind, , clean] = standing;
45 if (state === "diverged" && !clean) return { word: "conflicted", behind };
46 if (behind > 0) {
47 const idle = mode === "take-updates" && (tookAt === null || now - Date.parse(tookAt) > STALE_MS);
48 return { word: idle ? "quiet" : "behind", behind };
49 }
50 return { word: "following", behind: 0 };
51 }
52
53 /** The word as said: `following`, `behind 3`, `conflicted`, `severed`, `quiet`. */
54 export const linkText = (l: Pick<FlowLine, "link" | "behindBy">): string =>
55 l.link === undefined ? "" : l.link === "behind" ? `behind ${l.behindBy ?? 0}` : l.link;
56
57 const LINK_HEALTH: Record<LinkWord, Health> = { following: "ok", behind: "behind", conflicted: "diverged", severed: "off", quiet: "stale" };
58
2259 /** One thing a person may do about a link: a same-origin POST, or a link to a page. */
2360 export interface FlowAction {
2461 readonly label: string;
@@ -38,6 +75,10 @@ export interface FlowLine {
3875 readonly at: string | null;
3976 readonly problem: boolean;
4077 readonly health: Health;
78 /** For a fork's link to its parent: the one word for how it stands. */
79 readonly link?: LinkWord;
80 /** With `link` behind: how many commits. */
81 readonly behindBy?: number;
4182 /** The followed source's id, for the line that stops it. */
4283 readonly id?: string;
4384 readonly action?: FlowAction;
@@ -81,7 +122,7 @@ export function followHealth(
81122 return r.behind > 0 ? "behind" : "ok";
82123 }
83124
84 export function readFlows(db: Database, repo: Repo, viewer: User | undefined, now = Date.now()): FlowView {
125 export function readFlows(db: Database, repo: Repo, viewer: User | undefined, now = Date.now(), reposRoot?: string): FlowView {
85126 const writer = viewer !== undefined && viewer.kind !== "agent" && canWrite(db, repo, viewer);
86127 const admin = viewer !== undefined && viewer.kind !== "agent" && canAdmin(db, repo, viewer);
87128 const inbound: FlowLine[] = [];
@@ -89,8 +130,13 @@ export function readFlows(db: Database, repo: Repo, viewer: User | undefined, no
89130 if (repo.forkParentId !== null) {
90131 const parent = getRepoById(db, repo.forkParentId);
91132 if (parent && canRead(db, parent, viewer)) {
133 const mode = forkFollowMode(db, repo.id);
134 const tookAt = lastTookAt(db, repo.id);
135 const { word, behind } = linkWord(mode, reposRoot === undefined ? undefined : keptStanding({ reposRoot }, repo, parent), tookAt, now);
92136 inbound.push({
93 kind: "origin", label: `${parent.ownerName}/${parent.name}`, href: base(parent), state: "forked from", at: null, problem: false, health: "none",
137 kind: "origin", label: `${parent.ownerName}/${parent.name}`, href: base(parent), state: "forked from", at: tookAt, problem: word === "conflicted",
138 health: LINK_HEALTH[word], link: word,
139 ...(word === "behind" ? { behindBy: behind } : {}),
94140 ...(writer ? { action: { label: `Offer what's useful to ${parent.ownerName}/${parent.name}`, href: `${base(repo)}/pulls/new`, post: false } } : {}),
95141 });
96142 }
@@ -169,7 +215,8 @@ export function readFlows(db: Database, repo: Repo, viewer: User | undefined, no
169215 });
170216 }
171217 inbound.push(scanLine(db, repo));
172 // Forges that follow this one: a child forge holds a proposal token for it. Their names are for those who write here.
218 // Forges that follow this one: a child forge holds a proposal token for it. Their names are for
219 // those who write here.
173220 if (writer) {
174221 for (const c of db
175222 .query<{ child: string; origin: string; created_at: string; last_used_at: string | null; expires_at: string | null }, [string]>(
src/tui/screens/flows.ts +5 −5
@@ -13,7 +13,7 @@ import { probeLinks } from "../../flows/probe.ts";
1313 import { mayStartRadar, startRadar } from "../../flows/start.ts";
1414 import { actOnFollow } from "../../flows/act.ts";
1515 import { askUpdate, worthTaking } from "../../flows/file.ts";
16 import { readFlows, type FlowLine, type Health } from "../../flows/view.ts";
16 import { linkText, readFlows, type FlowLine, type Health } from "../../flows/view.ts";
1717 import type { Ctx, Screen } from "../app/app.ts";
1818 import { binding } from "../app/keys.ts";
1919 import type { Session } from "../session.ts";
@@ -23,7 +23,7 @@ const HEALTH_TONE: Partial<Record<Health, "danger" | "attn">> = { diverged: "dan
2323
2424 const flowRow = (side: string) => (l: FlowLine): ListRow => ({
2525 title: `${side} ${l.label}`,
26 secondary: l.state,
26 secondary: l.link === undefined ? l.state : `${l.state} · ${linkText(l)}`,
2727 ...(l.problem ? { tone: "danger" as const } : HEALTH_TONE[l.health] ? { tone: HEALTH_TONE[l.health]! } : {}),
2828 meta: l.at === null ? "never moved" : l.at.slice(0, 16).replace("T", " "),
2929 });
@@ -42,7 +42,7 @@ export function flowsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
4242 /** Rows in draw order, each with the line or package it stands for. */
4343 const items = (): { row: ListRow; line?: FlowLine; dep?: DepLine }[] => {
4444 if (!visible()) return [];
45 const view = readFlows(f.db, repo, f.user);
45 const view = readFlows(f.db, repo, f.user, Date.now(), f.app.reposRoot);
4646 return [
4747 ...view.inbound.map((line) => ({ row: flowRow("in ")(line), line })),
4848 ...deps.map((dep) => ({ row: depRow(dep), dep })),
@@ -52,8 +52,8 @@ export function flowsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
5252 const rows = (): ListRow[] => items().map((i) => i.row);
5353 const selected = () => items()[state.index];
5454 /** The actions the page would offer this person: the same reads decide. */
55 const actions = () => (visible() ? readFlows(f.db, repo, f.user).inbound.flatMap((l) => (l.action && l.kind === "origin" ? [l.action] : [])) : []);
56 const mayFollow = () => (visible() ? readFlows(f.db, repo, f.user).inbound.some((l) => l.action?.post && (l.kind === "source" || l.kind === "upstream")) : false);
55 const actions = () => (visible() ? readFlows(f.db, repo, f.user, Date.now(), f.app.reposRoot).inbound.flatMap((l) => (l.action && l.kind === "origin" ? [l.action] : [])) : []);
56 const mayFollow = () => (visible() ? readFlows(f.db, repo, f.user, Date.now(), f.app.reposRoot).inbound.some((l) => l.action?.post && (l.kind === "source" || l.kind === "upstream")) : false);
5757 const load = async (signal?: AbortSignal): Promise<void> => {
5858 if (signal) live(f, signal, { repoId: repo.id, kinds: ["repo.links_probed", "repo.upstream_checked", "issue.opened"] }, () => ctx.invalidate());
5959 deps = visible() ? readRadar(f.db, repo.id, await pinsOf(f.app, repo)) : [];
src/web/pages/flows.ts +3 −3
@@ -15,7 +15,7 @@ import { depState, readRadar } from "../../flows/radar.ts";
1515 import { pinsOf } from "../../flows/run.ts";
1616 import { probeLinks } from "../../flows/probe.ts";
1717 import { mayStartRadar, startRadar } from "../../flows/start.ts";
18 import { readFlows, type FlowAction, type FlowLine, type Health } from "../../flows/view.ts";
18 import { linkText, readFlows, type FlowAction, type FlowLine, type Health } from "../../flows/view.ts";
1919 import type { Ctx } from "../../http/context.ts";
2020 import { crumbsFor, loadRepo, notFoundPage, pageHead, repoBase, repoHeader, repoPalette } from "../chrome.ts";
2121 import { field, readForm } from "../form.ts";
@@ -29,7 +29,7 @@ export const lineRow = (l: FlowLine): Html =>
2929 ...(l.href === "" ? {} : { href: l.href }),
3030 title: html`${l.label}`,
3131 meta: html`${l.at === null ? "never moved" : time(l.at)}`,
32 trail: badge(l.state, { tone: TONE[l.health] }),
32 trail: badge(l.link === undefined ? l.state : `${l.state} · ${linkText(l)}`, { tone: TONE[l.health] }),
3333 });
3434
3535 /** A link's tone from its health: `attn` and `danger` are Tone values the badge already has. */
@@ -68,7 +68,7 @@ export async function flowsPage(ctx: Ctx): Promise<Response> {
6868 const repo = loadRepo(ctx);
6969 if (!repo) return notFoundPage(ctx);
7070 const rendering = performance.now();
71 const flows = readFlows(ctx.app.db, repo, ctx.auth.user);
71 const flows = readFlows(ctx.app.db, repo, ctx.auth.user, Date.now(), ctx.app.reposRoot);
7272 const deps = readRadar(ctx.app.db, repo.id, await pinsOf(ctx.app, repo));
7373 const admin = mayStartRadar(ctx.app, repo, ctx.auth.user);
7474 const writer = ctx.auth.user !== undefined && ctx.auth.user.kind !== "agent" && canWrite(ctx.app.db, repo, ctx.auth.user);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs