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

docs/DESIGN.md: generate its shared lists from the areas' files (child of #14248) #14383

Merged opened this

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

Merged

scout/forge:scout/14354-docs-design-md-generate-its-shared-lists → main 2 commits fork 1 thread · 1 unresolved

  • Merged. scout/14354-docs-design-md-generate-its-shared-lists was merged into main as e2e6b37.

Review

Sign in to review this change.
36 files changed +240 −39
AGENTS.md +1 −1
@@ -2,7 +2,7 @@
22
33 Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
44
5 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`).
5 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). The section list of `docs/DESIGN.md` is built the same way: a section file under `docs/design/sections/` opens with `order:` and `nest:` front matter and its first heading is its title (#14354, `test/design-spine.test.ts`).
66
77 README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
88 A pull that adds a page (`src/web/pages/*.ts`) also adds a terminal screen under `src/tui/screens/` that another module imports (its palette entry) and a `docs/features/<name>.md`, or a commit line `No door: <why>`; a new `src/web/render/*.ts`, `src/web/studio/*.ts` or `src/actions/*.ts` is asked for the screen alone, and a new feature module under `src/` in a pull that edits an existing page is asked for both, and a pull that edits an existing page (or any shared `src/web/` file, #13376: a new feature module wired into it is asked for both) changes something under `src/tui/` and a `docs/features/*.md` too (#13196); an edited API route, MCP tool or `src/actions/*.ts` changes something under `src/tui/` too (#14040); a new `src/http/api/*.ts` or `src/http/mcp/tools/*.ts` is asked for the screen, and a new module wired into `src/http/server.ts` for both (#14320); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
docs/DESIGN.md +7 −33
@@ -56,39 +56,13 @@ has a name for, that is the bug.
5656 Read this once. It is short on purpose.
5757
5858 Each section is its own file under `docs/design/sections/`, so a change to one
59 never conflicts with a change to another. This page is the spine: it orders
60 them, and the design check (`bun scripts/design-lint.ts`) reads them in this
61 order — a section file not listed here is not part of the contract. A new
62 component class is named in `docs/design/areas/<area>.md`, not here.
59 never conflicts with a change to another. The list below is built from them when
60 read (#14354), never typed: a section opens with front matter, `order:` (a
61 number; sections run lowest first, so leave gaps) and `nest:` (how deep it
62 sits in the list), and its title is its first heading. The design check
63 (`bun scripts/design-lint.ts`) reads them in that order. A new component class
64 is named in `docs/design/areas/<area>.md`, not here.
6365
6466 ---
6567
66 - [1. Principles](design/sections/1-principles.md)
67 - [2. Tokens](design/sections/2-tokens.md)
68 - [3. Typography](design/sections/3-typography.md)
69 - [4. Space, radius, motion](design/sections/4-space-radius-motion.md)
70 - [5. The component vocabulary](design/sections/5-components.md)
71 - [5a. Saying where you are reading from](design/sections/5a-reading-from.md)
72 - [5b. The workflow units](design/sections/5b-workflow-units.md)
73 - [5c. Apps, runs and the crew](design/sections/5c-apps-runs-crew.md)
74 - [5d. Page-local classes](design/sections/5d-page-local-classes.md)
75 - [6. Keyboard](design/sections/6-keyboard.md)
76 - [6a. The code browser](design/sections/6a-code-browser.md)
77 - [6b. Code, coloured](design/sections/6b-code-coloured.md)
78 - [6c. The editor](design/sections/6c-editor.md)
79 - [6·0. The pointer](design/sections/6-0-pointer.md)
80 - [6·0a. The dashboard's panes](design/sections/6-0a-dashboard-panes.md)
81 - [6·0a·1. Laid out for the terminal it is in](design/sections/6-0a-1-terminal-layout.md)
82 - [6·0b. Icons, and the appearance picker](design/sections/6-0b-icons-appearance.md)
83 - [6·0c. Pictures in the terminal](design/sections/6-0c-terminal-pictures.md)
84 - [6a. Counts and marks on a row](design/sections/6a-counts-and-marks.md)
85 - [6b. The workspace — one screen for a whole repository](design/sections/6b-workspace.md)
86 - [6c. Editing, and the commit dialog](design/sections/6c-editing-commit-dialog.md)
87 - [6c·1. Contributing: fork at the origin, propose a change](design/sections/6c-1-contributing.md)
88 - [6d. `$FORGE_EDITOR` — the operator's own editor, over a pty](design/sections/6d-forge-editor.md)
89 - [6e. Links that work](design/sections/6e-links.md)
90 - [6e·1. Reviews, threads, and the merge gate](design/sections/6e-1-reviews-merge-gate.md)
91 - [6f. Realtime](design/sections/6f-realtime.md)
92 - [6g. Apps, runs and the crew, where the terminal still shows them](design/sections/6g-terminal-apps-runs-crew.md)
93 - [7. Two rules that are security boundaries](design/sections/7-security-boundaries.md)
94 - [8. Checklist before you call a screen done](design/sections/8-checklist.md)
68 <!-- sections -->
docs/design/sections/1-principles.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 10
3 nest: 0
4 ---
15 ## 1. Principles
26
37 1. **Border-first, not shadow-first.** Elevation in a light theme is a hairline
docs/design/sections/2-tokens.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 20
3 nest: 0
4 ---
15 ## 2. Tokens
26
37 Palettes live in `src/design/themes.ts`; the stylesheet only ever reads
docs/design/sections/3-typography.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 30
3 nest: 0
4 ---
15 ## 3. Typography
26
37 ```
docs/design/sections/4-space-radius-motion.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 40
3 nest: 0
4 ---
15 ## 4. Space, radius, motion
26
37 - **4px grid.** Every padding, margin and gap is divisible by 4; 6px is allowed
docs/design/sections/5-components.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 50
3 nest: 0
4 ---
15 ## 5. The component vocabulary
26
37 Implemented in `src/web/ui.ts` (pure) and `src/web/chrome.ts` (may read the
docs/design/sections/5a-reading-from.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 60
3 nest: 1
4 ---
15 ### 5a. Saying where you are reading from
26
37 Every repository page in the product carries the **where strip**, and it says
docs/design/sections/5b-workflow-units.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 70
3 nest: 1
4 ---
15 ### 5b. The workflow units
26
37 A unit is a whole intention with one button behind it, not a sequence of
docs/design/sections/5c-apps-runs-crew.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 80
3 nest: 1
4 ---
15 ### 5c. Apps, runs and the crew
26
37 `docs/APPS.md` is the contract; these are its units on a page, and the same
docs/design/sections/5d-page-local-classes.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 90
3 nest: 1
4 ---
15 ### 5d. Page-local classes
26
37 The close form on an issue's thread is no class at all: its reason select and
docs/design/sections/6-0-pointer.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 140
3 nest: 1
4 ---
15 ### 6·0. The pointer
26
37 The terminal UI is keyboard-first and mouse-**complete**: everything you can
docs/design/sections/6-0a-1-terminal-layout.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 160
3 nest: 1
4 ---
15 ### 6·0a·1. Laid out for the terminal it is in
26
37 Three numbers in `ui/layout.ts` decide every screen's shape, so every screen
docs/design/sections/6-0a-dashboard-panes.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 150
3 nest: 1
4 ---
15 ### 6·0a. The dashboard's panes
26
37 `Repositories`, `Recent activity`, `On you`, `On your machine`,
docs/design/sections/6-0b-icons-appearance.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 170
3 nest: 1
4 ---
15 ### 6·0b. Icons, and the appearance picker
26
37 Two vocabularies. **`plain`** is the safe set (§6a) — BMP, width 1, in every
docs/design/sections/6-0c-terminal-pictures.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 180
3 nest: 1
4 ---
15 ### 6·0c. Pictures in the terminal
26
37 A tab whose path looks like an image and whose bytes git returned as binary is
docs/design/sections/6-keyboard.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 100
3 nest: 0
4 ---
15 ## 6. Keyboard
26
37 Driven entirely from the DOM: `data-shortcut="g i"` on a link, `data-nav` on a
docs/design/sections/6a-code-browser.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 110
3 nest: 1
4 ---
15 ### 6a. The code browser
26
37 Tree and blob pages are one layout, not two: a `.code-layout` grid with the
docs/design/sections/6a-counts-and-marks.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 190
3 nest: 1
4 ---
15 ### 6a. Counts and marks on a row
26
37 Three glyphs carry the at-a-glance numbers, all of them BMP, all width 1, all
docs/design/sections/6b-code-coloured.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 120
3 nest: 1
4 ---
15 ### 6b. Code, coloured
26
37 One tokenizer, `src/web/highlight.ts`, serves the file browser, the diff
docs/design/sections/6b-workspace.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 200
3 nest: 1
4 ---
15 ### 6b. The workspace — one screen for a whole repository
26
37 Opening a repository in the terminal opens a **workspace**, not a home page:
docs/design/sections/6c-1-contributing.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 220
3 nest: 1
4 ---
15 ### 6c·1. Contributing: fork at the origin, propose a change
26
37 The workflow the origins layer exists for — _grab their repo, branch, edit,
docs/design/sections/6c-editing-commit-dialog.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 210
3 nest: 1
4 ---
15 ### 6c. Editing, and the commit dialog
26
37 `e` turns the active tab into a modeless editor: arrows/Home/End/PgUp/PgDn and
docs/design/sections/6c-editor.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 130
3 nest: 1
4 ---
15 ### 6c. The editor
26
37 `GET /:owner/:name/edit/:ref/*path` is a `<textarea>` in a `<form>`, and one
docs/design/sections/6d-forge-editor.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 230
3 nest: 1
4 ---
15 ### 6d. `$FORGE_EDITOR` — the operator's own editor, over a pty
26
37 `E` suspends the UI and hands the terminal to `$FORGE_EDITOR` on a real pty.
docs/design/sections/6e-1-reviews-merge-gate.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 250
3 nest: 1
4 ---
15 ### 6e·1. Reviews, threads, and the merge gate
26
37 A pull is judged in three places, and each says one thing.
docs/design/sections/6f-realtime.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 260
3 nest: 1
4 ---
15 ### 6f. Realtime
26
37 Dashboard, issue and pull lists, the repo home, and the issue and pull screens
docs/design/sections/6g-terminal-apps-runs-crew.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 270
3 nest: 1
4 ---
15 ### 6g. Apps, runs and the crew, where the terminal still shows them
26
37 The terminal's half of §5c is deliberately small: running an app and
docs/design/sections/7-security-boundaries.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 280
3 nest: 0
4 ---
15 ## 7. Two rules that are security boundaries
26
37 **Label colors.** Inline `style=""` is blocked by the CSP — nonces apply to
docs/design/sections/8-checklist.md +4
@@ -1,3 +1,7 @@
1 ---
2 order: 290
3 nest: 0
4 ---
15 ## 8. Checklist before you call a screen done
26
37 1. Every divider is exactly 1px. The only 2px things are the active-tab
scripts/design-lint.ts +12 −2
@@ -67,6 +67,7 @@
6767
6868 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
6969 import { join, relative } from "node:path";
70 import { parseSection, renderSpine, stripSection } from "../src/view/design_spine.ts";
7071 import { dictateFindings } from "../src/design/dictate.ts";
7172 import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts";
7273 import { contrastFindings } from "../src/design/contrast.ts";
@@ -249,10 +250,19 @@ export function sectionLinks(spine: string): string[] {
249250 return [...spine.matchAll(/\]\(design\/sections\/([a-z0-9-]+\.md)\)/g)].map((m) => m[1]!);
250251 }
251252
253 /** The spine: DESIGN.md with its list of sections built from the section files (#14354). */
254 export function designSpine(root: string): string {
255 const dir = join(root, SECTIONS);
256 const sections = readdirSync(dir).filter((n) => n.endsWith(".md")).map((n) => ({ name: n, meta: parseSection(readFileSync(join(dir, n), "utf8")) }));
257 const bad = sections.filter((s) => s.meta === undefined).map((s) => s.name);
258 if (bad.length) throw new Error(`no usable front matter (order, a heading) in docs/design/sections: ${bad.join(", ")}`);
259 return renderSpine(readFileSync(join(root, DESIGN), "utf8"), sections);
260 }
261
252262 /** DESIGN.md as one text: the spine, then each section it links, in order (#5937). */
253263 export function designText(root: string): string {
254 const spine = readFileSync(join(root, DESIGN), "utf8");
255 return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n");
264 const spine = designSpine(root);
265 return [spine, ...sectionLinks(spine).map((f) => stripSection(readFileSync(join(root, SECTIONS, f), "utf8")))].join("\n");
256266 }
257267
258268 /**
src/view/design_spine.ts added +62
@@ -0,0 +1,62 @@
1 /**
2 * The list of sections in `docs/DESIGN.md` is built from the section files, never typed (#14354,
3 * the way of the features index, #14248). A section file opens with front matter:
4 *
5 * ---
6 * order: 140 (sections run lowest first; leave gaps so a new one fits between)
7 * nest: 1 (optional: how deep it sits in the list, 0 by default)
8 * ---
9 *
10 * and its title is its first `#` heading. DESIGN.md keeps one `<!-- sections -->` line where the
11 * list goes. A pull that adds a section adds that one file and edits no shared list. Plain data in,
12 * plain data out.
13 */
14
15 export interface SectionMeta {
16 readonly order: number;
17 readonly nest: number;
18 readonly title: string;
19 }
20
21 export interface Section {
22 readonly name: string;
23 readonly meta: SectionMeta | undefined;
24 }
25
26 const FRONT = /^---\n([\s\S]*?)\n---\n/;
27
28 /** The text of a section without its front matter. */
29 export function stripSection(text: string): string {
30 return text.replace(FRONT, "");
31 }
32
33 /** The front matter and title of a section, or undefined when `order` or the heading is missing. */
34 export function parseSection(text: string): SectionMeta | undefined {
35 const m = FRONT.exec(text);
36 if (m === null) return undefined;
37 const f = new Map<string, string>();
38 for (const line of (m[1] ?? "").split("\n")) {
39 const at = line.indexOf(": ");
40 if (at > 0) f.set(line.slice(0, at).trim(), line.slice(at + 2).trim());
41 }
42 const o = f.get("order");
43 if (o === undefined || !/^\d{1,6}$/.test(o)) return undefined;
44 const n = f.get("nest");
45 const nest = n !== undefined && /^[0-3]$/.test(n) ? Number(n) : 0;
46 const h = /^#{1,6} (.+)$/m.exec(text.slice(m[0].length));
47 if (h === null) return undefined;
48 return { order: Number(o), nest, title: (h[1] as string).trim() };
49 }
50
51 /** The head with the list of sections put where its `<!-- sections -->` line is. */
52 export function renderSpine(head: string, sections: readonly Section[]): string {
53 const list = sections
54 .flatMap((s) => (s.meta === undefined ? [] : [{ s, m: s.meta }]))
55 .sort((a, b) => a.m.order - b.m.order || a.s.name.localeCompare(b.s.name))
56 .map(({ s, m }) => `${" ".repeat(m.nest)}- [${m.title}](design/sections/${s.name})`)
57 .join("\n");
58 return head
59 .split("\n")
60 .map((l) => (l.trim() === "<!-- sections -->" ? list : l))
61 .join("\n");
62 }
src/view/docs.ts +6 −1
@@ -7,6 +7,7 @@
77 * for the life of the process.
88 */
99
10 import { parseSection, renderSpine } from "./design_spine.ts";
1011 import { parseFront, renderFeatureIndex, stripFront } from "./feature_index.ts";
1112 import { docsPages, renderDocsIndex } from "./docs_index.ts";
1213 import { readdirSync, readFileSync } from "node:fs";
@@ -51,10 +52,14 @@ export function docText(entry: DocEntry, ssh = false): string {
5152
5253 /**
5354 * A document as read: a note without its front matter, the features index built from the notes
54 * (#14248).
55 * (#14248), the design file's list of sections from the section files (#14354).
5556 */
5657 function readDoc(name: string): string {
5758 const text = readFileSync(join(DOCS, name), "utf8");
59 if (name === "DESIGN.md") {
60 const dir = join(DOCS, "design", "sections");
61 return renderSpine(text, readdirSync(dir).filter((n) => n.endsWith(".md")).map((n) => ({ name: n, meta: parseSection(readFileSync(join(dir, n), "utf8")) })));
62 }

Non-blocking: this duplicates the readdir-and-parse in designSpine() in scripts/design-lint.ts. Move one loader into design_spine.ts and call it from both.

5863 if (name === "README.md") return renderDocsIndex(text, docsPages(DOCS));
5964 if (name !== "features/README.md") return stripFront(text);
6065 const notes = readdirSync(join(DOCS, "features"))
test/design-lint.test.ts +2 −2
@@ -1,6 +1,6 @@
11 import { describe, expect, test } from "bun:test";
22 import { readdirSync, readFileSync } from "node:fs";
3 import { areaFiles, compareLayout, layoutCounts, layoutIn, scanLayout, classesIn, compare, compareQuiet, quiet, scanQuiet, scanCards, scanStranger, strangerWords, STRANGER_FILES, countFile, designText, documentedClasses, locate, loneSentenceCards, registeredClasses, overlay, overlayClassesIn, scanOverlay, scan, sectionLinks, webCss } from "../scripts/design-lint.ts";
3 import { areaFiles, compareLayout, layoutCounts, layoutIn, scanLayout, classesIn, compare, compareQuiet, quiet, scanQuiet, scanCards, scanStranger, strangerWords, STRANGER_FILES, countFile, designText, designSpine, documentedClasses, locate, loneSentenceCards, registeredClasses, overlay, overlayClassesIn, scanOverlay, scan, sectionLinks, webCss } from "../scripts/design-lint.ts";
44
55 /** A DESIGN.md in miniature: the §5 table, a §5d register, and a §6 that names a class too. */
66 const DESIGN = [
@@ -173,7 +173,7 @@ describe("docs/DESIGN.md", () => {
173173 });
174174
175175 test("the spine links every section file once, and each link is a file (#5937)", () => {
176 const linked = sectionLinks(readFileSync("docs/DESIGN.md", "utf8"));
176 const linked = sectionLinks(designSpine("."));
177177 expect(new Set(linked).size).toBe(linked.length);
178178 expect([...linked].sort()).toEqual(readdirSync("docs/design/sections").filter((n) => n.endsWith(".md")).sort());
179179 });
test/design-spine.test.ts added +34
@@ -0,0 +1,34 @@
1 /** The design file's list of sections is built from the section files (#14354). */
2 import { expect, test } from "bun:test";
3 import { readdirSync, readFileSync } from "node:fs";
4 import { parseSection, renderSpine, stripSection } from "../src/view/design_spine.ts";
5 import { docEntry, docText } from "../src/view/docs.ts";
6
7 const sec = (order: number, nest: number, title: string) => `---\norder: ${order}\nnest: ${nest}\n---\n## ${title}\n`;
8
9 test("sections run by order, nested by nest, titled by their heading", () => {
10 const out = renderSpine("a\n<!-- sections -->\nb", [
11 { name: "b.md", meta: parseSection(sec(20, 1, "Two")) },
12 { name: "a.md", meta: parseSection(sec(10, 0, "One")) },
13 ]);
14 expect(out).toBe("a\n- [One](design/sections/a.md)\n - [Two](design/sections/b.md)\nb");
15 });
16
17 test("front matter without an order or a heading is no section", () => {
18 expect(parseSection("## T\n")).toBeUndefined();
19 expect(parseSection("---\norder: x\n---\n## T\n")).toBeUndefined();
20 expect(parseSection("---\norder: 1\n---\nno heading\n")).toBeUndefined();
21 expect(stripSection(sec(1, 0, "T"))).toBe("## T\n");
22 });
23
24 test("every section file in the repository is usable, so the list lacks none", () => {
25 const dir = "docs/design/sections";
26 const names = readdirSync(dir).filter((n) => n.endsWith(".md"));
27 expect(names.length).toBeGreaterThan(0);
28 for (const n of names) expect(parseSection(readFileSync(`${dir}/${n}`, "utf8"))).toBeDefined();
29 const e = docEntry("DESIGN.md");
30 expect(e).toBeDefined();
31 const text = docText(e!);
32 for (const n of names) expect(text).toContain(`(design/sections/${n})`);
33 expect(text).not.toContain("<!-- sections -->");
34 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs