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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/15162-forge-help-lists-each-command-once-in-th → main 4 commits fork 2 threads · 2 unresolved
3 files
changed +43
−3
src/cli/commands/index.ts +2 −1
| @@ -1,5 +1,6 @@ | ||
| 1 | 1 | /** |
| 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 | |
| 3 | 4 | * command is a new file in this directory plus one line here. |
| 4 | 5 | */ |
| 5 | 6 | import { command as ui } from "./ui.ts"; |
src/cli/help.ts +15 −2
| @@ -1,5 +1,6 @@ | ||
| 1 | 1 | import { configPath, rootDir } from "./config.ts"; |
| 2 | 2 | import { commands } from "./commands/index.ts"; |
| 3 | import type { Command } from "./commands/types.ts"; | |
| 3 | 4 | import type { Out } from "./out.ts"; |
| 4 | 5 | |
| 5 | 6 | /** |
| @@ -11,12 +12,24 @@ export const VERSION = "0.0.1"; | ||
| 11 | 12 | /** Where the flags column starts, so every command's notes line up. */ |
| 12 | 13 | const FLAGS_COLUMN = 31; |
| 13 | 14 | |
| 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`. */ | |
| 15 | 28 | export function printUsage(out: Out): void { |
| 16 | 29 | const b = (text: string): string => out.paint(text, out.c.fg); |
| 17 | 30 | out.line(`forge ${VERSION} — your workbench, on this machine`); |
| 18 | 31 | out.line(); |
| 19 | for (const { usage } of commands) { | |
| 32 | for (const { usage } of helpOrder()) { | |
| 20 | 33 | const head = ` ${usage.synopsis}`; |
| 21 | 34 | out.line( |
| 22 | 35 | 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. | |
| 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 | }); |
new above
offline
Non-blocking: matching on the description text is brittle. Derive the word from usage.synopsis instead.