IF Commons GitHub

Terminal

0001Draft

0001-terminal · owner if · domain commons

The command line

FR-001checkpassing

Terminal MUST parse an argument vector against options declared once as data (flags, negatable flags, single values, repeatable values, each decoded by a parser or a decoder of Core, with defaults or required), inferring the parsed value's type from the declaration and refusing at compile time a short letter declared twice, a dashed key and the key help; take --name VALUE, --name=VALUE, -x VALUE and bundled short flags, end options at --, and treat help as a result of its own that wins over every error; refuse, by a typed error that says one sentence with a suggestion for a near name, an undeclared option, a missing, unexpected or attached value, an invalid value, an option given twice, a required option missing and an undeclared argument; and write help text from the same declaration.

Enforced (check): .github: cd commons/terminal && bun test suite/ — args.test.ts: every grammar rule and error kind with its sentence and suggestion, the help text, type inference with negative controls, random declarations written into command lines and parsed back

Proved by: terminal/suite/args.test.ts

Written in: terminal/src/args.ts

Tests: passed: suite/args.test.ts -- ends the options and the words after it are kept apart; - and -5 are arguments; passed: suite/args.test.ts a malformed declaration does not compile (negative controls); passed: suite/args.test.ts a negatable flag: --name gives true, --no-name false, absent its default or undefined; passed: suite/args.test.ts a repeatable option keeps every value in order; values are parsed by a function or a decod; passed: suite/args.test.ts a required option not given is refused; given, its type has no undefined and 16 more

Cited by: args, Terminal

FR-002checkpassing

Terminal MUST give a command tree declared once as data (commands): a command of groups and verbs, each with a name (lower case, [a-z][a-z0-9-]*), a summary, and for a verb its options (FR-001's declaration) and arguments, to any depth; MUST resolve an argument vector to the verb it names and the arguments left for it, or to the group or verb whose help is asked for (--help, -h, or a group named with no verb), or to a typed error that says which word was not known at which level, the words that are known there and the nearest of them by FR-001's suggest; and MUST render a command's, a group's and a verb's help from that declaration alone, so that help never runs a verb.

Enforced (check): .github: cd commons/terminal && bun test suite/ — commands.test.ts: a tree resolved to its verb, help asked at every level, unknown words with suggestions, help rendered from the declaration

Proved by: terminal/suite/commands.test.ts

Written in: terminal/src/commands.ts

Tests: passed: suite/commands.test.ts a word not known is named with where, the words known there, and the nearest; passed: suite/commands.test.ts an argument vector resolves to its verb, with the words after it left for the verb; passed: suite/commands.test.ts help is asked for at every level, and names the node it is for; passed: suite/commands.test.ts help is rendered from the declaration alone: a group's commands, a verb's options, argumen; passed: suite/commands.test.ts the problems of a declared tree: names that may not be one, and two children of one name

Cited by: commands, Terminal

The console

FR-003checkpassing

The palette MUST be one: colour roles as a union type, and the marks ✅ (done), ❌ (failed), ⏭️ (skipped), ⏹️ (cancelled), 👉 (hint), ⚠️ (warning), ⏳ (pending) and ⚡ (action), each with an ASCII fallback ([ok], [x], [skip], [stop], ->, [!], [todo], [you]) used where the terminal has no emoji; colour MUST be used only where the terminal's capabilities allow it, always reset after, and never for a plain or an empty text.

Enforced (check): .github: cd commons/terminal && bun test suite/ — palette.test.ts: the palette's roles, marks and their ASCII fallbacks, colour only where allowed

Proved by: terminal/suite/palette.test.ts

Written in: terminal/src/palette.ts

Tests: passed: suite/palette.test.ts a painted text without colour is the text, and with colour reads back as the text (propert; passed: suite/palette.test.ts colour only where it is allowed, always reset after, never for plain or an empty text; passed: suite/palette.test.ts every mark is one emoji of two columns, with its ASCII fallback where there are no emoji; passed: suite/palette.test.ts the roles and marks are closed unions, and a runtime Look is a Capabilities

Cited by: Signals

FR-004checkpassing

Terminal MUST measure a text by display width (a wide character or emoji counts two columns, a combining mark and an escape sequence none) and cut a text to a number of columns, never inside a grapheme (found with Intl.Segmenter) or an escape sequence, and MUST reset the style that is open at the cut.

Enforced (check): .github: cd commons/terminal && bun test suite/ — width.test.ts: wide characters and escape sequences, a line cut by display width, never inside a grapheme or an escape sequence

Proved by: terminal/suite/vt.test.ts, terminal/suite/width.test.ts

Written in: terminal/src/width.ts

Tests: passed: suite/vt.test.ts a line cut to the width never wraps, and leaves no style on (property); passed: suite/width.test.ts a line holding ✅ 测试 at a width of 6 is cut after 测; passed: suite/width.test.ts a text cut fits its width, and its head and tail make the text and its width again (proper; passed: suite/width.test.ts escape sequences are kept whole, and a style open at the cut is reset; passed: suite/width.test.ts wide characters and emoji take two columns, marks and escape sequences none

FR-005checkpassing

Terminal MUST give a small terminal emulator (carriage return, line feed, backspace, cursor up and down, erase in line and in display, colour sequences kept apart from the text, a screen that grows or one of a given height that scrolls) so that a test can take a snapshot of what a person would see after every frame.

Enforced (check): .github: cd commons/terminal && bun test suite/ — vt.test.ts: the terminal emulator's sequences, scrolling, wide characters and a cut line that never wraps

Proved by: terminal/suite/vt.test.ts

Written in: terminal/src/vt.ts

Tests: passed: suite/vt.test.ts a line cut to the width never wraps, and leaves no style on (property); passed: suite/vt.test.ts a screen of a given height scrolls; passed: suite/vt.test.ts carriage return, line feed, backspace and tab; passed: suite/vt.test.ts colour sequences are kept apart from the text, cell by cell; passed: suite/vt.test.ts cursor movement and erase in line and in display redraw a live region in place and 3 more

Cited by: Signals

The package

FR-006checkno test run

Terminal MUST depend on Core alone, MUST name no host global, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/terminal (commons 0032-libraries-by-concern FR-005), with an entry for the package and an entry for each of args, commands, palette, vt and width, so that it runs on Bun, on Node 26 and in a browser.

Enforced (check): .github: cd commons/terminal && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs every entry on Node 26 and Bun and type-checks a consumer

Written in: terminal/about.ts, terminal/library.ts, terminal/src/mod.ts, terminal/tools/check.ts, terminal/tools/pack.ts

Acceptance scenarios

  1. Given options declared once, When a command line with --jsn is parsed where --json is declared, Then it is refused with did you mean --json?, per FR-001.
  2. Given a command tree with the group work, When tool wrk build is resolved, Then an error names wrk at the top level with work as the suggestion, per FR-002.
  3. Given a terminal with no emoji, When a mark is written, Then its ASCII fallback is, per FR-003.
  4. Given a line holding ✅ 测试 and a width of 6, When it is cut, Then it is cut after 测, per FR-004.
  5. Given a live region redrawn with cursor movements, When the emulator is fed the bytes, Then it shows the text a person would see, per FR-005.
  6. Given the packed package installed under node_modules, When Node 26 and Bun import each entry, Then both give the same parse, per FR-006.

Out of scope

  • The terminal's size and its standard streams, and the console that renders OpenTelemetry signals (the libraries system and telemetry), and what each command does (the program that declares it).

Edge cases

  • --verbose --verbose: refused as repeated, never silently taken once, per FR-001.
  • tool work build --help: the verb's help, and its handler never called, per FR-002.
  • A text of wide characters at a width of one column: cut to nothing rather than inside a character, per FR-004.

Assumptions

  • ECMAScript 2024 and the web standards (Intl.Segmenter) are all that the code needs.

Open questions

  • None.

Key entities

  • Options declaration - the data from which the parser, its type and its help are all made.
  • Command tree - groups and verbs declared once, resolved from an argument vector.
  • Palette - the colour roles and marks of the console, each mark with its ASCII fallback.

Success criteria

SC-001success criterion

A program declares its command line once and gets its parser, its types, its help and its errors from that.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

args, commands, Terminal, Signals

Titles, headings, exports, tables, columns and requirements. Esc closes.