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

A tell from the terminal's home screen carries the screen's context and prints its receipt #13184

Merged opened this

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

Merged

scout/forge:scout/13167-a-tell-from-the-terminal-s-home-screen-c → main 7 commits fork 2 threads · 2 unresolved

  • Merged. scout/13167-a-tell-from-the-terminal-s-home-screen-c was merged into main as 71ce7cd.

Review

Sign in to review this change.
12 files changed +338 −5
docs/features/README.md +1
@@ -93,6 +93,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
9393 - [A run's state is worked out from what it did](run-state.md)
9494 - [A team is told once that a pull waits on its review](team-waits.md)
9595 - [A tell from a preview's toolbar carries its pull](toolbar-tell.md)
96 - [Tell the crew from the terminal's screen: key M](tell-from-here.md)
9697 - [A write the restart cut short, in a conversation](talk-resume-writes.md)
9798 - [Actions that answer at once](act-now.md)
9899 - [A thread folds its settled history](thread-fold.md)
docs/features/tell-from-here.md added +9
@@ -0,0 +1,9 @@
1 # Tell the crew from where you are (#13167)
2
3 `M` in the terminal tells the crew from the screen you are on, so the tell carries the address a person would otherwise have to type.
4
5 - Where it works: the repository workspace, the issue and pull lists, an issue, a pull, the runs list and a run's log. Any screen that can say where it is (`Screen.here`) has the key; the app asks it, so a screen adds no check or binding of its own. Only people who may direct the crew on that repository see `M` in the footer or get the prompt.
6 - The prompt: "Tell the crew", labelled `from alice/notes issue #3` (a pull reads `pull #4`, a run `run <id>`, the workspace just the repository). Type one line, `enter` sends, `esc` cancels.
7 - The tell: it opens an issue whose body starts `Told from [/alice/notes/issues/3](...)`, the same line the web's tell pill writes.
8 - The receipt: one toast, `Told from alice/notes issue #3 — receipt: issue #7. Opened as issue #7. …`. The receipt number leads, so a long answer is cut after it, never before.
9 - Code: `src/tui/screens/tell_here.ts` (`tellHook`, `tellHere`), the loop's `TellHook` in `src/tui/app/app.ts`; tests in `test/tui-tell-context.test.ts`.
src/tui/app/app.ts +23 −2
@@ -64,6 +64,7 @@ import {
6464 } from "../ui/widgets.ts";
6565 import { binding, find, keyFor, type Binding } from "./keys.ts";
6666 import { message } from "../screens/common.ts";
67 import type { Here } from "../screens/tell_here.ts";
6768 import { Palette, type Command, type PaletteSearch } from "./palette.ts";
6869 import { truncate } from "../term/width.ts";
6970
@@ -90,6 +91,8 @@ export interface Screen {
9091 commands?(): Command[];
9192 /** The local repository this screen shows, so `leaveRepo` can find it when it is deleted. */
9293 readonly repoId?: string;
94 /** Where this screen is, for the tell key (`screens/tell_here.ts`); absent: no tell key here. */
95 here?(): Here | undefined;
9396 }
9497
9598 /**
@@ -281,6 +284,19 @@ export interface AppOpts extends SessionOpts {
281284 * `ctx.setTheme`. The loop knows nothing about persistence; the host does.
282285 */
283286 readonly onTheme?: (name: ThemeName) => void;
287 /**
288 * The key that tells the crew from the focused screen (#13167). The loop only asks: the host
289 * says whether the screen has a place to tell from, and takes the key.
290 */
291 readonly tell?: TellHook;
292 }
293
294 /** What the host does for the tell key, given the focused screen. */
295 export interface TellHook {
296 /** The hint, empty when this screen has no place to tell from or this person may not. */
297 keys(screen: Screen): Binding[];
298 /** True when the key was taken. */
299 key(screen: Screen, ctx: Ctx, e: KeyEvent): boolean;
284300 }
285301
286302 export class App {
@@ -789,6 +805,10 @@ export class App {
789805 };
790806 }
791807
808 private tellKeys(): Binding[] {
809 return this.opts.tell?.keys(this.top().screen) ?? [];
810 }
811
792812 private onKey(e: KeyEvent): void {
793813 this.invalidate();
794814 // Ctrl+C always quits, from any overlay and any screen; Ctrl+Z is
@@ -803,6 +823,7 @@ export class App {
803823 // it has focus — but a screen that does not handle them cannot swallow
804824 // them either.
805825 if (this.top().screen.key(e)) return;
826 if (this.opts.tell?.key(this.top().screen, this.ctx, e)) return;
806827
807828 // Ctrl+Z is swallowed *after* the screen has had it: over SSH there is no
808829 // process group to suspend into, so it must never reach a shell — but the
@@ -1124,7 +1145,7 @@ export class App {
11241145 });
11251146 return;
11261147 }
1127 const bindings = [...this.top().screen.keys, ...this.globals];
1148 const bindings = [...this.top().screen.keys, ...this.tellKeys(), ...this.globals];
11281149 // A hint in the bar is a *button*: clicking one presses the key it names,
11291150 // which is the shortest possible path from "I can see what this does" to
11301151 // doing it. Disabled hints are drawn and not registered.
@@ -1144,7 +1165,7 @@ export class App {
11441165
11451166 private drawHelp(area: Rect, c: Tokens): void {
11461167 const s = this.surface;
1147 const bindings = [...this.top().screen.keys, ...this.globals].filter(
1168 const bindings = [...this.top().screen.keys, ...this.tellKeys(), ...this.globals].filter(
11481169 (b) => b.hidden !== true,
11491170 );
11501171 const inner = card(s, area, c, { title: "Keys", focused: true });
src/tui/forge.ts +2
@@ -122,6 +122,7 @@ import { openNewApp, templateAppScreen } from "./screens/newapp.ts";
122122 import { newRepoScreen } from "./screens/newrepo.ts";
123123 import { repoScreen } from "./screens/repo.ts";
124124 import { signInScreen } from "./screens/signin.ts";
125 import { tellHook } from "./screens/tell_here.ts";
125126 import { local } from "./screens/where.ts";
126127
127128 export { Session, type TuiIdentity };
@@ -926,6 +927,7 @@ export function createForgeApp(
926927 search: forgeSearch(session),
927928 onTheme: (name) => session.saveTheme(name),
928929 onPrefs: (prefs) => session.savePrefs(prefs),
930 tell: tellHook(session),
929931 });
930932 return { app, session };
931933 }
src/tui/screens/issue.ts +1
@@ -569,6 +569,7 @@ export function issueScreen(
569569
570570 const screen: Screen = {
571571 title: `#${number}`,
572 here: () => (repo === undefined ? undefined : { repo, issue: number }),
572573 get keys() {
573574 return [
574575 ...(crew.runs.length > 0
src/tui/screens/issues.ts +1
@@ -264,6 +264,7 @@ export function issuesScreen(
264264
265265 const screen: Screen = {
266266 title: kind === "pull" ? "Pulls" : "Issues",
267 here: () => (repo === undefined ? undefined : { repo }),
267268 get keys() {
268269 return [
269270 binding(["j", "k"], "move"),
src/tui/screens/pull.ts +13 −3
@@ -252,7 +252,10 @@ const CHECK_TICK_MS = 5000;
252252 export const GUEST_NOTE = "a guest: no app variables, no crew, until a writer approves";
253253 /** The same on an autonomous repository, where the crew's reviewer reads it first (#9575). */
254254 export const GUEST_NOTE_FILTERED = "a guest: no app variables until a writer approves; the crew reviews it first";
255 /** An outside agent's branch (`core/contribute_token.ts`): checked already, its preview without the app's settings until `G`. */
255 /**
256 * An outside agent's branch (`core/contribute_token.ts`): checked already, its preview without the
257 * app's settings until `G`.
258 */
256259 export const OUTSIDE_NOTE = "from an outside contributor: approve (G) to run its preview with this app's settings";
257260
258261 export function pullScreen(
@@ -271,7 +274,10 @@ export function pullScreen(
271274 let next: Next | null = null;
272275 /** Which of check, review, land, live the pull is at; the page's step line. */
273276 let step: PathStep | null = null;
274 /** Where an approved open pull stands in the landing queue; the page's line under its path (#10860). */
277 /**
278 * Where an approved open pull stands in the landing queue; the page's line under its path
279 * (#10860).
280 */
275281 let landing: string | null = null;
276282 /** Where each team the issue names stands; empty when it names none. */
277283 let teams: TeamVerdict[] = [];
@@ -334,7 +340,10 @@ export function pullScreen(
334340 let ledgerLine = "";
335341 /** What the access wall holds this open pull for, read from git (#7847). */
336342 let wall: Wall | undefined;
337 /** What happens next to a stranger's open pull, the page's sentence (`crew/stranger.ts`); empty for anyone else's. */
343 /**
344 * What happens next to a stranger's open pull, the page's sentence (`crew/stranger.ts`); empty
345 * for anyone else's.
346 */
338347 let strangerLine = "";
339348 /** `h` is a person's key: an agent's hold is refused by the action, so it is not offered. */
340349 const mayHold = (): boolean =>
@@ -1130,6 +1139,7 @@ export function pullScreen(
11301139
11311140 const screen: Screen = {
11321141 title: `#${number}`,
1142 here: () => (repo === undefined ? undefined : { repo, pull: number }),
11331143 get keys() {
11341144 const takeBackKey = mayTakeBack();
11351145 return [
src/tui/screens/runlog.ts +1
@@ -52,6 +52,7 @@ export function runLogScreen(
5252
5353 const self: Screen = {
5454 title: "Run log",
55 here: () => ({ repo, run: runId }),
5556 get keys() {
5657 return [
5758 binding(["j", "k"], "scroll"),
src/tui/screens/runs.ts +1
@@ -127,6 +127,7 @@ export function runsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
127127
128128 const self: Screen = {
129129 title: "Runs",
130 here: () => ({ repo }),
130131 get keys() {
131132 return [
132133 binding(["j", "k"], "move"),
src/tui/screens/tell_here.ts added +93
@@ -0,0 +1,93 @@
1 /**

The how-to for this feature belongs in docs/features/<name>.md, which is missing. Also centralise the 'may tell here' check and key binding here instead of repeating it in four screens.

2 * Tell the crew from where you are (#13167): `M` on the workspace, an issue,
3 * a pull or a run log sends one line to that screen's repository with the
4 * screen's own address as the tell's `from` — the same field the web pill
5 * fills — names it in the prompt and the confirm line, and prints the receipt
6 * (the issue the tell opened) when it is sent. One module, one concept: the
7 * screens only say where they are.
8 */
9
10 import { tell as sendTell } from "../../actions/tell.ts";
11 import { tellAnswer } from "../../actions/tell_answer.ts";
12 import { SAY_SOMETHING_WORDS } from "../../actions/tell_words.ts";
13 import type { Repo } from "../../core/repos.ts";
14 import { mayDirectCrew } from "../../crew/direct.ts";
15 import type { Ctx, Screen, TellHook } from "../app/app.ts";
16 import { binding } from "../app/keys.ts";
17 import type { Session } from "../session.ts";
18 import { promptScreen } from "./common.ts";
19
20 /** Where a screen is: its repository, and the issue, pull or run it shows. */
21 export interface Here {
22 readonly repo: Repo;
23 readonly issue?: number;
24 readonly pull?: number;
25 readonly run?: string;
26 }
27
28 /** The sender; `tell` itself, or a fake in a test. */
29 export type Sender = typeof sendTell;
30
31 /** The key every context screen binds. */
32 export const TELL_KEY = "M";
33
34 /** The screen's name in words: `alice/notes issue #3`. */
35 export function hereWords(h: Here): string {
36 const name = `${h.repo.ownerName}/${h.repo.name}`;
37 if (h.issue !== undefined) return `${name} issue #${h.issue}`;
38 if (h.pull !== undefined) return `${name} pull #${h.pull}`;
39 if (h.run !== undefined) return `${name} run ${h.run}`;
40 return name;
41 }
42
43 /** The screen's same-forge address, the tell's `from`. */
44 export function herePath(h: Here): string {
45 const base = `/${h.repo.ownerName}/${h.repo.name}`;
46 if (h.issue !== undefined) return `${base}/issues/${h.issue}`;
47 if (h.pull !== undefined) return `${base}/pulls/${h.pull}`;
48 if (h.run !== undefined) return `${base}/runs/${h.run}`;
49 return base;
50 }
51
52 /** One tell from `h`: the answer, then the receipt, in one confirm line. */
53 export async function tellHereNow(f: Pick<Session, "app" | "user">, ctx: Pick<Ctx, "toast">, h: Here, said: string, send: Sender = sendTell): Promise<void> {
54 const told = await send(f.app, f.user, h.repo, said, 1, herePath(h));
55 const answer = tellAnswer(told);
56 // The receipt leads: a long answer is cut to the toast's width, the number must not be.
57 const lead = told.ok ? `Told from ${hereWords(h)} — receipt: issue #${told.value.issue.number}. ` : "";
58 ctx.toast(`${lead}${answer.text}`, answer.tone);
59 }
60
61 /** Whether this person may tell the crew from `h`: the check no screen repeats. */
62 function mayTell(f: Session, h: Here | undefined): h is Here {
63 return h !== undefined && f.user !== undefined && mayDirectCrew(f.db, h.repo, f.user);
64 }
65
66 /**
67 * The prompt, for who may direct the crew here; nothing for anyone else. Returns whether the key
68 * was taken.
69 */
70 export function tellHere(f: Session, ctx: Ctx, parent: Screen, h: Here | undefined, send: Sender = sendTell): boolean {
71 if (!mayTell(f, h)) return false;
72 ctx.push(
73 promptScreen(ctx, parent, {
74 title: "Tell the crew",
75 label: `from ${hereWords(h)}`,
76 hint: "enter sends",
77 onSubmit: (said) => (said === "" ? SAY_SOMETHING_WORDS : tellHereNow(f, ctx, h, said, send)),
78 }),
79 );
80 return true;
81 }
82
83 /**
84 * The one mechanism: the app asks the focused screen where it is (`Screen.here`), and this says
85 * whether `M` is offered and takes it. A screen that can answer `here` has the key; none repeats
86 * the check or the binding.
87 */
88 export function tellHook(f: Session, send: Sender = sendTell): TellHook {
89 return {
90 keys: (screen) => (mayTell(f, screen.here?.()) ? [binding([TELL_KEY], "tell the crew")] : []),
91 key: (screen, ctx, e) => e.key === TELL_KEY && !e.ctrl && !e.alt && tellHere(f, ctx, screen, screen.here?.(), send),
92 };
93 }
src/tui/screens/workspace.ts +1
@@ -2092,6 +2092,7 @@ export function workspaceScreen(
20922092
20932093 const screen: Screen = {
20942094 ...(repo === undefined ? {} : { repoId: repo.id }),
2095 here: () => (repo === undefined ? undefined : { repo }),
20952096 commands: () => [
20962097 ...workingCommands(f, ctx, repo),
20972098 ...tellCommands(f, ctx, () => screen, repo),
test/tui-tell-context.test.ts added +192
@@ -0,0 +1,192 @@
1 /**
2 * The tell key on the terminal's context screens (#13167): the workspace and
3 * an issue send the screen's own address as the tell's `from`, say where in
4 * the confirm line and print the receipt; a fake sender proves the words for
5 * a pull and a run too; a stranger's key is not taken.
6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { openPull } from "../src/actions/pulls.ts";
12 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
13 import { tell } from "../src/actions/tell.ts";
14 import { createApp, type App } from "../src/app.ts";
15 import { listIssues } from "../src/core/issues.ts";
16 import type { Repo } from "../src/core/repos.ts";
17 import { createUser, type User } from "../src/core/users.ts";
18 import { createForgeApp } from "../src/tui/forge.ts";
19 import { issueScreen } from "../src/tui/screens/issue.ts";
20 import { issuesScreen } from "../src/tui/screens/issues.ts";
21 import { pullScreen } from "../src/tui/screens/pull.ts";
22 import { runLogScreen } from "../src/tui/screens/runlog.ts";
23 import { runsScreen } from "../src/tui/screens/runs.ts";
24 import { hereWords, herePath, tellHereNow, type Sender } from "../src/tui/screens/tell_here.ts";
25 import { local } from "../src/tui/screens/where.ts";
26 import { workspaceScreen } from "../src/tui/screens/workspace.ts";
27 import { headlessTerminal } from "../src/tui/term/terminal.ts";
28 import { quietLogs } from "./helpers/globals.ts";
29 import { settleApp } from "./helpers/tui.ts";
30 import { proveAll } from "./helpers/verified.ts";
31
32 quietLogs();
33
34 let dir = "";
35 let app: App;
36 let alice: User;
37 let bob: User;
38 let repo: Repo;
39 let issueNumber = 0;
40 let PULL = 4;
41 const RUN = "r1";
42
43 const issues = () => listIssues(app.db, repo.id, { state: "all", limit: 50 });
44
45 type Where = "workspace" | "issue" | "pull" | "runlog" | "issues" | "runs";
46
47 async function drive(user: User, screen: Where, keys: string[]): Promise<string> {
48 const terminal = headlessTerminal(120, 30);
49 const { app: tui, session } = createForgeApp(
50 app,
51 { sshUsername: user.username, remoteAddress: "127.0.0.1", user },
52 { terminal, exitHooks: false },
53 );
54 tui.start();
55 await settleApp(tui);
56 const src = local(session, repo);
57 const built = {
58 workspace: () => workspaceScreen(session, tui.ctx, src),
59 issue: () => issueScreen(session, tui.ctx, src, issueNumber),
60 pull: () => pullScreen(session, tui.ctx, src, PULL),
61 runlog: () => runLogScreen(session, tui.ctx, repo, RUN),
62 issues: () => issuesScreen(session, tui.ctx, src, "issue"),
63 runs: () => runsScreen(session, tui.ctx, repo),
64 }[screen]();
65 tui.push(built);
66 await settleApp(tui);
67 for (const k of keys) {
68 terminal.feed(k);
69 await settleApp(tui);
70 }
71 const text = tui.screen.toText();
72 tui.stop();
73 return text;
74 }
75
76 beforeAll(async () => {
77 dir = await mkdtemp(join(tmpdir(), "forge-tui-tell-context-"));
78 app = createApp({ dataDir: dir, port: 0 });
79 const mk = async (username: string, first = false) => {
80 const r = await createUser(app.db, {
81 origin: "seed", trusted: true, username, email: `${username}@forge.local`,
82 password: "a-good-passphrase", adminIfFirst: first,
83 });
84 if (!r.ok) throw new Error(r.error);
85 return r.value;
86 };
87 alice = await mk("alice", true);
88 bob = await mk("bob");
89 proveAll(app);
90 const made = await createRepo(app, alice, { name: "notes", visibility: "public" });
91 if (!made.ok) throw new Error(String(made.error));
92 repo = made.value;
93 const first = await tell(app, alice, repo, "Add a footer.");
94 if (!first.ok) throw new Error(first.error);
95 issueNumber = first.value.issue.number;
96 const base = await commitToBranch(app, alice, repo, {
97 branch: "main",
98 message: "Start",
99 files: [{ path: "README.md", content: "notes\n" }],
100 });
101 if (!base.ok) throw new Error(JSON.stringify(base.error));
102 const committed = await commitToBranch(app, alice, repo, {
103 branch: "tweak",
104 message: "A tweak",
105 files: [{ path: "tweak.md", content: "hi\n" }],
106 });
107 if (!committed.ok) throw new Error(JSON.stringify(committed.error));
108 const opened = await openPull(app, alice, repo, { title: "A tweak", baseBranch: "main", headBranch: "tweak" });
109 if (!opened.ok) throw new Error(String(opened.error));
110 PULL = opened.value.number;
111 });
112
113 afterAll(async () => {
114 app.close();
115 await rm(dir, { recursive: true, force: true });
116 });
117
118 describe("M on a context screen", () => {
119 test("the issue screen tells from its own address, names it and prints the receipt", async () => {
120 const before = issues().length;
121 const text = await drive(alice, "issue", ["M", ..."Make it blue.", "\r"]);
122 const told = issues().find((i) => i.title === "Make it blue.")!;
123 expect(issues().length).toBe(before + 1);
124 const page = `/alice/notes/issues/${issueNumber}`;
125 expect(told.body).toContain(`Told from [${page}](${page})`);
126 expect(text).toContain(`Told from alice/notes issue #${issueNumber} —`);
127 expect(text).toContain(`receipt: issue #${told.number}`);
128 });
129
130 test("the workspace tells from the repository", async () => {
131 const text = await drive(alice, "workspace", ["M", ..."Add a footer link.", "\r"]);
132 const told = issues().find((i) => i.title === "Add a footer link.")!;
133 expect(told.body).toContain("Told from [/alice/notes](/alice/notes)");
134 expect(text).toContain("Told from alice/notes —");
outdated

Mis-indented line. More importantly, the pull and runlog screens need a key-driven test, not just tellHereNow.

135 expect(text).toContain(`receipt: issue #${told.number}`);
136 });
137
138 test("the pull screen tells from the pull's address", async () => {
139 const text = await drive(alice, "pull", ["M", ..."Rebase it.", "\r"]);
140 const told = issues().find((i) => i.title === "Rebase it.")!;
141 expect(told.body).toContain(`Told from [/alice/notes/pulls/${PULL}](/alice/notes/pulls/${PULL})`);
142 expect(text).toContain(`Told from alice/notes pull #${PULL} —`);
143 expect(text).toContain(`receipt: issue #${told.number}`);
144 });
145
146 test("the run log tells from the run's address", async () => {
147 const text = await drive(alice, "runlog", ["M", ..."Why red?", "\r"]);
148 const told = issues().find((i) => i.title === "Why red?")!;
149 expect(told.body).toContain(`/alice/notes/runs/${RUN}`);
150 expect(text).toContain(`Told from alice/notes run ${RUN} —`);
151 expect(text).toContain(`receipt: issue #${told.number}`);
152 });
153
154 test("the lists of issues and runs carry the key too, and offer it in the footer", async () => {
155 for (const where of ["issues", "runs"] as const) {
156 expect(await drive(alice, where, ["?"])).toContain("tell the crew");
157 expect(await drive(alice, where, ["M"])).toContain("from alice/notes");
158 expect(await drive(bob, where, ["?"])).not.toContain("tell the crew");
159 }
160 });
161
162 test("the prompt names where it is sent from", async () => {
163 expect(await drive(alice, "issue", ["M"])).toContain(`from alice/notes issue #${issueNumber}`);
164 });
165
166 test("a stranger's key opens nothing", async () => {
167 const before = issues().length;
168 const text = await drive(bob, "issue", ["M", ..."Sneak.", "\r"]);
169 expect(text).not.toContain("Tell the crew");
170 expect(issues().length).toBe(before);
171 });
172
173 test("a fake client hears the pull's and the run's address; a refusal prints no receipt", async () => {
174 const calls: { from: string | null }[] = [];
175 const toasts: string[] = [];
176 const ctx = { toast: (t: string) => void toasts.push(t) };
177 const f = { app, user: alice };
178 const fake: Sender = (a, u, r, said, v, from = null, fa) => {
179 calls.push({ from });
180 return tell(a, u, r, said, v, from, fa);
181 };
182 await tellHereNow(f, ctx, { repo, pull: 4 }, "x", fake);
183 await tellHereNow(f, ctx, { repo, run: "r1" }, "x", fake);
184 expect(calls.map((c) => c.from)).toEqual(["/alice/notes/pulls/4", "/alice/notes/runs/r1"]);
185 expect(toasts[0]).toContain("Told from alice/notes pull #4 —");
186 expect(toasts[0]).toMatch(/receipt: issue #\d+\./);
187 expect(hereWords({ repo, run: "r1" })).toBe("alice/notes run r1");
188 expect(herePath({ repo })).toBe("/alice/notes");
189 await tellHereNow({ app, user: bob }, ctx, { repo, pull: 4 }, "x");
190 expect(toasts[2]).not.toContain("receipt");
191 });
192 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs