v0.30.0 lw --tui, compose pipeline on screen

doc/cli.md

@@ -6,6 +6,7 @@ lw -c|--config FILE [options]
 lw -p|--preset NAME[,KEY=VALUE...] [options]
 lw -t|--check [options]
 lw --dump [options]
+lw -T|--tui [options]
 lw auth COMMAND [flags]
 lw tls COMMAND [flags]
 lw preset NAME [flags]
@@ -31,7 +32,7 @@ first argument.
 - lw's own options have a long form (`--config`), and the frequent ones a
   one-letter short form that stands for it in every command that has it:
   - `-c` `--config`, `-p` `--preset`, `-q` `--quiet`, `-t` `--check`,
-    `-V` `--version`, `-h` `--help`
+    `-T` `--tui`, `-V` `--version`, `-h` `--help`
   - `-u` `--user` in `lw auth` and `lw preset edge`
 - A value follows as the next argument or after `=` (`-c FILE`, `-c=FILE`,
   `--config FILE`, `--config=FILE`); a value that starts with `-` follows `=`,
@@ -66,6 +67,8 @@ pipelines have [their own flags](#pipelines):
   exit; see [Usage Patterns](#usage-patterns)
 - `--dump`: print the effective configuration, flags, environment and presets
   resolved into it, as TOML that `-c` reads back, and exit
+- `-T`, `--tui`: compose the pipelines on screen, then run or print them
+  ([below](#lw---tui))
 - `--schema`: print every setting, pipeline flag, flow stage, plugin option
   and preset as one JSON document (kinds, defaults, rules, help), and exit;
   tools build their option lists from it
@@ -430,6 +433,40 @@ kill -HUP  $(pidof lw)
 kill -USR1 $(pidof lw)
 ```
 
+## `lw --tui`
+
+`lw --tui` (`-T`) composes pipelines on a full-screen terminal, drawn as the
+website's configurator draws them, with the engine the website runs as
+WebAssembly.
+
+- Start: the pipelines `lw` would run with the same options (`-c FILE`,
+  pipeline flags, `LOGWISP_SOURCE`, a discovered file); with none but the
+  built-in pipe, the preset menu (or `empty`). A pasted `lw` command line
+  replaces the pipelines, in the preset menu too.
+- Screen: SOURCES, FLOW and SINKS side by side from 64 columns, stacked
+  below; each source and sink a tinted bar with its type, whether it listens
+  or dials, and a summary; the four flow stages in their order in a dashed
+  box, the ones off dimmed. The inspector, the chosen part's options, sits
+  below the canvas, and beside it from 110 columns.
+- Keys: arrows or `hjkl` move; Enter inspects, then edits a value (empty
+  returns it to its default); Tab sets it and goes to the next; Esc back; `a` adds a source,
+  sink or filter; `d` deletes, or returns a value to its default; Space turns
+  a flow stage or a switch on or off; `J`/`K` move a filter; `[` `]` switch
+  pipelines; `p` presets; `c` shows the first problem; `o` output; `?` keys;
+  `q` quits.
+- Output, `o`: run the pipelines with the other options given (so `--check`
+  and `--dump` apply to them, and reloads keep them), or print one of the
+  command line, the environment variables (one pipeline) and the file's
+  pipelines on standard output once the screen closes.
+- The screen draws on the controlling terminal: `lw -T > pipelines.toml` and
+  `cmd | lw -T` keep standard input and output as data. lw never writes the
+  file it starts from, but the shell empties a redirect's target before lw
+  reads it: redirect to a file lw does not load.
+- Color follows the `color` setting: `auto` the terminal and `NO_COLOR`,
+  `always` the terminal, `never` none. True color and 256 colors paint the
+  website's dark theme; 16 colors and none keep the terminal's own; a text
+  console draws with CP437 glyphs, and a terminal outside UTF-8 with ASCII.
+
 ## `lw auth`
 
 Manages the credentials files of `auth.type = "scram"` listeners and logs in to

doc/lw.1

@@ -20,6 +20,9 @@
 .Op Fl \-rate\-limit Ar spec
 .Op Fl \-heartbeat Ar spec
 .Nm
+.Fl T | Fl \-tui
+.Op Ar options
+.Nm
 .Cm auth | tls | preset | config
 .Ar command
 .Op Ar flags
@@ -146,6 +149,23 @@ Print the effective configuration, with the options, environment and
 presets resolved into it, as a file
 .Fl c
 reads back, and exit.
+.It Fl T , Fl \-tui
+Compose pipelines on a full-screen terminal, starting from the ones
+.Nm
+would run with the other options given, or from a preset when that is only
+the built-in standard input to standard output pipe.
+On leaving, run them with the other options, as
+.Fl \-check
+and
+.Fl \-dump
+also do, or print them as a command line, environment variables or a
+configuration file's pipelines.
+The screen draws on the controlling terminal, so standard input and output
+stay data:
+.Ql lw \-T > pipelines.toml .
+A file is read, never written; the shell empties a redirect's target before
+.Nm
+reads it, so the redirect names a file it does not load.
 .It Fl \-schema
 Print every setting, pipeline flag, flow stage, plugin option and preset as
 one JSON document, with kinds, defaults, rules and help, and exit; tools build

doc/todo.md

@@ -109,61 +109,11 @@ Steps:
 1. Schema, in `internal/config`: done.
 2. Engine, `internal/compose`: done.
 3. `lw --schema`: done. The site generates its catalogue from it.
-4. In `lixenwraith/terminal`, released and pinned before the TUI:
-   - Full-screen 8- and 16-color output (SGR 30-37, 90-97, 40-47) and the
-     default colors 39/49; it emits only 256-color and truecolor today.
-   - Detection as `inline` does it: 16 colors on text consoles, none under
-     `NO_COLOR`, refusal on `TERM=dumb`, and an override for LogWisp's `color`
-     key.
-   - Drawing on `/dev/tty`, so `lw --tui > logwisp.toml` and `cmd | lw --tui`
-     keep stdin and stdout as data.
-   - Bracketed paste into text fields.
-   - `tui` widgets the site's controls have: segmented choice, filterable
-     option list, toggle, typed fields (default as placeholder, required mark,
-     error and help line, folded groups), a focus ring; every widget styled
-     from one `tui.Theme`.
-   - In `color`, optional: export the 16 xterm reference shades. RGBTo16 maps
-     the site's hues badly (green to cyan, red to bright black), so the
-     8-color tier is chosen by hand.
-5. `lw --tui`.
-   - A parser switch, `-T` for short (`-t` is `--check`). With `-c FILE`,
-     pipeline flags or `LOGWISP_SOURCE` it starts from that composition, and
-     never rewrites FILE (TOML encoding drops its comments); bare, it opens the
-     preset menu (pipe, tail, serve, edge, aggregator, empty).
-   - The pipeline as the site draws it: SOURCES, FLOW, SINKS; a node is a
-     tinted bar, its type, listens or dials, and a summary line; the four flow
-     stages in order inside a dashed box, the ones off dimmed; wires drawn from
-     per-cell connectivity so every junction is right. The inspector sits
-     below at 80 to 109 columns, beside at 110 and over; under 64 columns the
-     stages stack, as on the site.
-     ```
-      ● SOURCES              ● FLOW                       ● SINKS
-      ▌ file             ─┐  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮  ┌─▌ http      listens
-      ▌ /var/log  *.log   │  ╎ ▌ rate_limit 400/s   ╎  │ ▌ :8080  /stream
-      █ tcp_chain listens─┴─►╎ ▌ filters -TRACE     ╎─►┤
-      █ :9000  tls  scram    ╎ ▌ format txt         ╎  └─▌ console
-                             ╎ ○ heartbeat off      ╎    ▌ stdout
-                             ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯
-     ── tcp_chain · source · id src-2 ─────────────────── ⏎ edit  tab next ──
-        host     0.0.0.0  default        format   raw [txt] json
-        port *   9000▌                   tls      ▸ on   (auth, acl folded)
-      ✓ valid   a add  d delete  ␣ on/off  J/K move  p preset  o output  ? help
-     ```
-   - Keys: arrows or hjkl move, Enter edits, `a` adds from the catalogue, `d`
-     deletes, Space switches a flow stage, `J`/`K` reorder filters, `p`
-     presets, `[` `]` switch pipelines, `c` lists errors, `o` output, `?`
-     help, `q` quits.
-   - Theme: the site's dark tokens as one role table in four tiers. Truecolor
-     and 256 colors paint the site's background; 8 colors and mono keep the
-     terminal's. Sources cyan, flow violet, sinks green, accent blue, muted
-     grey, errors red. A selection always changes a glyph (bar, `▸`,
-     underline), never only a shade. Glyphs: Unicode, a CP437 set on text
-     consoles, ASCII outside UTF-8.
-   - Output, `o`: Run hands `config.Args` built from the composition to the
-     usual `config.Load`, after the terminal is released and before anything
-     reads stdin; reloads keep the pipelines, and `--tui --check` and `--tui
-     --dump` follow. Or exactly one of command line, environment and file,
-     printed to stdout once the screen closes.
+4. `lixenwraith/terminal` v0.2.0: done: 16 and no color, the terminal's
+   default colors, `/dev/tty`, bracketed paste, themed form controls. Still
+   optional, in `color`: export the 16 xterm reference shades (RGBTo16 maps
+   the site's hues badly, so the 16-color tier is chosen by hand).
+5. `lw --tui`: done ([doc/cli.md](cli.md#lw---tui)).
 6. WebAssembly: `cmd/lwconf` (`js && wasm`) exposes schema, preset, parse,
    validate and emit to the page as JSON strings. `make wasm` builds
    `bin/lwconf.wasm` with the version stamped, copies the toolchain's