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

`forge help` lists each command once, in the order a person meets them, with one line each #15183

Merged opened this

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

Merged

scout/forge:scout/15162-forge-help-lists-each-command-once-in-th → main 4 commits fork 2 threads · 2 unresolved

  • Merged. scout/15162-forge-help-lists-each-command-once-in-th was merged into main as d178827.

Review

Sign in to review this change.
3 files changed +43 −3
src/cli/commands/index.ts +2 −1
@@ -1,5 +1,6 @@
11 /**
2 * Every `forge` subcommand, in the order `forge help` lists them. A new
2 * Every `forge` subcommand, in registration order; `helpOrder` in `../help.ts`
3 * decides what `forge help` shows first. A new
34 * command is a new file in this directory plus one line here.
45 */
56 import { command as ui } from "./ui.ts";
src/cli/help.ts +15 −2
@@ -1,5 +1,6 @@
11 import { configPath, rootDir } from "./config.ts";
22 import { commands } from "./commands/index.ts";
3 import type { Command } from "./commands/types.ts";
34 import type { Out } from "./out.ts";
45
56 /**
@@ -11,12 +12,24 @@ export const VERSION = "0.0.1";
1112 /** Where the flags column starts, so every command's notes line up. */
1213 const FLAGS_COLUMN = 31;
1314
14 /** `forge help`: one line per command, in the table's order. */
15 /**
16 * The order a person meets them: sign in, make, tell, decide (`asks` is where
17 * asks are decided), then the rest as the table has them.
18 */
19 export const FIRST = ["login", "new", "tell", "asks"] as const;
20
21 /** Every command once: `FIRST`, then the others in table order. */
22 export function helpOrder(all: readonly Command[] = commands): Command[] {
23 const first = FIRST.flatMap((n) => all.filter((c) => c.name === n));
24 return [...first, ...all.filter((c) => !(FIRST as readonly string[]).includes(c.name))];
25 }
26
27 /** `forge help`: one line per command, in `helpOrder`. */
1528 export function printUsage(out: Out): void {
1629 const b = (text: string): string => out.paint(text, out.c.fg);
1730 out.line(`forge ${VERSION} — your workbench, on this machine`);
1831 out.line();
19 for (const { usage } of commands) {
32 for (const { usage } of helpOrder()) {
2033 const head = ` ${usage.synopsis}`;
2134 out.line(
2235 usage.flags === undefined
test/cli-help-order.test.ts added +26
@@ -0,0 +1,26 @@
1 import { expect, test } from "bun:test";
2 import { commands } from "../src/cli/commands/index.ts";
3 import { printUsage } from "../src/cli/help.ts";
4 import { createOut } from "../src/cli/out.ts";
5
6 function help(): string[] {
7 const lines: string[] = [];
8 printUsage({ ...createOut(), line: (t = "") => void lines.push(t) });
9 return lines
10 .map((l) => l.replace(/\x1b\[[0-9;]*m/g, ""))
11 .filter((l) => l.startsWith(" forge"));
12 }
13
14 test("help opens with login, new, tell, asks, then the rest", () => {
15 const rows = help();
16 expect(rows.slice(0, 4).map((r) => r.split(/\s+/)[2] ?? "")).toEqual(["login", "new", "tell", "asks"]);
17 });
18
19 test("help lists each registered command exactly once, one line each", () => {
20 const rows = help();
21 // The bare `forge` line (the local UI) has no command word of its own.

Non-blocking: matching on the description text is brittle. Derive the word from usage.synopsis instead.

22 const word = (r: string): string => (r.includes("the local terminal UI") ? "ui" : r.split(/\s+/)[2] ?? "");
23 const words = rows.map(word).sort();
outdated

Replace this nested-ternary expect with a plain comparison of the command words in help against commands.map(c => c.name), sorted. Same guarantee, readable.

24 expect(rows.length).toBe(commands.length);
25 expect(words).toEqual(commands.map((c) => c.name).sort());
26 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs