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

The terminal's tell takes its text from stdin, so `git diff | forge tell` steers in one thought #12722

Merged opened this

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

Merged

scout/forge:scout/12693-the-terminal-s-tell-takes-its-text-from → main 4 commits fork 1 thread · 1 unresolved

  • Merged. scout/12693-the-terminal-s-tell-takes-its-text-from was merged into main as 87a5df7.

Review

Sign in to review this change.
4 files changed +195 −6
docs/CLI.md +9
@@ -318,6 +318,15 @@ Tell the crew something about a repository; it becomes an issue. The
318318 repository is that of this folder's `origin` when it points at the workbench,
319319 or `--repo`. Words are 1 to 2000 characters; start them with a dash after `--`.
320320
321 With no words and piped input, `git diff | forge tell` tells what was piped
322 (at most 8 KB of valid UTF-8, control characters stripped; over the cap or
323 empty it refuses). The 2000-character limit on words applies to the cleaned
324 text and is checked before anything is sent: a long diff is refused saying how
325 many characters it is. CRLF becomes a newline; tabs and newlines are kept.
326 Stdin is read whenever it is not a terminal, so a bare `forge tell` in a
327 script whose stdin is open but silent waits for it to close; pass words, or
328 `</dev/null`, to get the usage line.
329
321330 Flags:
322331
323332 - `--repo owner/name` — the repository, instead of this folder's origin.
src/cli/commands/tell.ts +31 −6
@@ -5,19 +5,44 @@ import { requireConfig } from "../context.ts";
55 import { EXIT } from "../exit.ts";
66 import { resolveRepo } from "../here.ts";
77 import { inert, type Out } from "../out.ts";
8 import { readPiped, STDIN_MAX } from "../stdin_text.ts";
89 import type { Command } from "./types.ts";
910
11 const SAY =
12 "forge tell: say something — " +
13 'forge tell "words" [--repo owner/name] [--variants 1-4] [--from /path]';
14
1015 /**
1116 * `forge tell "words"`: tell the crew something about a repository; it
1217 * becomes an issue. Every rule here is the server's, checked early.
1318 */
1419 async function tell(out: Out, args: Args): Promise<number> {
15 const text = args.positional.join(" ").trim();
20 let text = args.positional.join(" ").trim();
21 if (text === "" && process.stdin.isTTY !== true) {
22 // No words given and something piped: `git diff | forge tell`.
23 const piped = await readPiped(Bun.stdin.stream());
24 if (piped.kind === "too_big") {
25 out.err(`forge tell: piped text is over ${STDIN_MAX} bytes (the cap)`);
26 return EXIT.usage;
27 }
28 if (piped.kind === "not_utf8") {
29 out.err("forge tell: piped text is not valid UTF-8");
30 return EXIT.usage;
31 }
32 if (piped.kind === "empty") {
33 out.err(`forge tell: nothing to tell — the piped text is empty\n${SAY}`);
34 return EXIT.usage;
35 }
36 if (piped.text.length > TELL_TEXT_MAX) {
37 out.err(
38 `forge tell: piped text is ${piped.text.length} characters and the limit is ${TELL_TEXT_MAX}`,
39 );
40 return EXIT.usage;
41 }
42 text = piped.text;
43 }
1644 if (text === "") {
17 out.err(
18 "forge tell: say something — " +
19 'forge tell "words" [--repo owner/name] [--variants 1-4] [--from /path]',
20 );
45 out.err(SAY);
2146 return EXIT.usage;
2247 }
2348 if (text.length > TELL_TEXT_MAX) {
@@ -69,7 +94,7 @@ async function tell(out: Out, args: Args): Promise<number> {
6994 export const command: Command = {
7095 name: "tell",
7196 usage: {
72 synopsis: "forge tell <words…>",
97 synopsis: "forge tell <words…> | … | forge tell",
7398 flags: "[--repo owner/name] [--variants 1-4] [--from /path] [--]",
7499 },
75100 run: tell,
src/cli/stdin_text.ts added +50
@@ -0,0 +1,50 @@
1 /** Words piped into a command: `git diff | forge tell`. */
2
3 /** The most bytes of piped text a command reads; a tell is held to 2000 characters on top. */
4 export const STDIN_MAX = 8192;

8 KB is the read cap, but the server takes 2000 characters, so anything between is read, cleaned and then refused late. Enforce TELL_TEXT_MAX in the piped branch with a message naming both numbers.

5
6 export type Piped =
7 | { kind: "text"; text: string }
8 | { kind: "empty" }
9 | { kind: "too_big" }
10 | { kind: "not_utf8" };
11
12 /** Control characters but newline and tab, and the unicode line separators. */
13 const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u2028\u2029]/g;
14
15 /** Validate and clean already-read bytes; pure. */
16 export function cleanPiped(bytes: Uint8Array): Piped {
17 if (bytes.length > STDIN_MAX) return { kind: "too_big" };
18 let text: string;
19 try {
20 text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
21 } catch {
22 return { kind: "not_utf8" };
23 }
24 text = text.replace(/\r\n?/g, "\n").replace(CONTROL, "").trim();
25 return text === "" ? { kind: "empty" } : { kind: "text", text };
26 }
27
28 /** Read at most STDIN_MAX+1 bytes from `stream`, then clean them. Never shells out. */
29 export async function readPiped(stream: ReadableStream<Uint8Array>): Promise<Piped> {
30 const chunks: Uint8Array[] = [];
31 let total = 0;
32 const reader = stream.getReader();
33 try {
34 while (total <= STDIN_MAX) {
35 const { done, value } = await reader.read();
36 if (done) break;
37 chunks.push(value);
38 total += value.length;
39 }
40 } finally {
41 await reader.cancel().catch(() => undefined);
42 }
43 const all = new Uint8Array(total);
44 let at = 0;
45 for (const c of chunks) {
46 all.set(c, at);
47 at += c.length;
48 }
49 return cleanPiped(all);
50 }
test/tell-stdin.test.ts added +105
@@ -0,0 +1,105 @@
1 /** `… | forge tell`: piped text is the words; same API call, same receipt. */
2
3 import { afterAll, beforeAll, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { EXIT } from "../src/cli/main.ts";
8 import { cleanPiped, STDIN_MAX } from "../src/cli/stdin_text.ts";
9
10 const CLI = new URL("../src/cli/main.ts", import.meta.url).pathname;
11 let server: ReturnType<typeof Bun.serve>;
12 let base = "";
13 let dir = "";
14 const seen: { text: string }[] = [];
15
16 beforeAll(async () => {
17 dir = await mkdtemp(join(tmpdir(), "forge-tell-stdin-"));
18 server = Bun.serve({
19 port: 0,
20 async fetch(req) {
21 seen.push((await req.json()) as { text: string });
22 return Response.json({ issue: 7, says: "Told the crew.", url: `${base}/alice/shop/issues/7` }, { status: 201 });
23 },
24 });
25 base = `http://127.0.0.1:${server.port}`;
26 });
27 afterAll(async () => {
28 server.stop(true);
29 await rm(dir, { recursive: true, force: true });
30 });
31
32 async function pipe(input: Uint8Array | string) {
33 const proc = Bun.spawn(["bun", CLI, "tell", "--repo", "alice/shop"], {
34 cwd: dir,
35 env: {
36 PATH: process.env["PATH"] ?? "",
37 HOME: process.env["HOME"] ?? "",
38 FORGE_URL: base,
39 FORGE_TOKEN: "tok",
40 FORGE_CONFIG_DIR: dir,
41 FORGE_KEYCHAIN: "0",
42 NO_COLOR: "1",
43 },
44 stdin: new Blob([input]),
45 stdout: "pipe",
46 stderr: "pipe",
47 });
48 const [out, err, code] = await Promise.all([
49 new Response(proc.stdout).text(),
50 new Response(proc.stderr).text(),
51 proc.exited,
52 ]);
53 return { out, err, code };
54 }
55
56 test("piped text is told, control characters stripped, with the usual receipt", async () => {
57 const run = await pipe("fix this\x1b[31m diff\x07\nline two\n");
58 expect(run.code).toBe(EXIT.ok);
59 expect(seen.at(-1)!.text).toBe("fix this[31m diff\nline two");
60 expect(run.out).toContain("Told the crew.");
61 expect(run.out).toContain("issue #7");
62 });
63
64 test("empty stdin says nothing to tell and sends nothing", async () => {
65 const before = seen.length;
66 const run = await pipe(" \n\x07");
67 expect(run.code).toBe(EXIT.usage);
68 expect(run.err).toContain("nothing to tell");
69 expect(seen.length).toBe(before);
70 });
71
72 test("oversize stdin refuses and names the cap", async () => {
73 const before = seen.length;
74 const run = await pipe("a".repeat(STDIN_MAX + 1));
75 expect(run.code).toBe(EXIT.usage);
76 expect(run.err).toContain(String(STDIN_MAX));
77 expect(seen.length).toBe(before);
78 });
79
80 test("invalid UTF-8 is refused", () => {
81 expect(cleanPiped(new Uint8Array([0xff, 0xfe, 0x41])).kind).toBe("not_utf8");
82 expect(cleanPiped(new TextEncoder().encode("héllo")).kind).toBe("text");
83 });
84
85 test("piped text over the 2000-character limit is refused locally with both numbers", async () => {
86 const before = seen.length;
87 const run = await pipe("a".repeat(3000));
88 expect(run.code).toBe(EXIT.usage);
89 expect(run.err).toContain("piped text is 3000 characters and the limit is 2000");
90 expect(seen.length).toBe(before);
91 });
92
93 test("CRLF becomes newline, tabs and newlines stay", async () => {
94 const run = await pipe("a\r\nb\tc\nd\re");
95 expect(run.code).toBe(EXIT.ok);
96 expect(seen.at(-1)!.text).toBe("a\nb\tc\nd\ne");
97 });
98
99 test("no stdin content gets the usage message and sends nothing", async () => {
100 const before = seen.length;
101 const run = await pipe("");
102 expect(run.code).toBe(EXIT.usage);
103 expect(run.err).toContain("say something");
104 expect(seen.length).toBe(before);
105 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs