@staix/cli-output 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +19 -2
- package/docs/standard-v1.md +138 -0
- package/fixtures/v1/color.json +204 -0
- package/fixtures/v1/error-line.json +5 -0
- package/fixtures/v1/markers.json +10 -0
- package/fixtures/v1/report/golden-ascii.json +131 -0
- package/fixtures/v1/report/golden.json +131 -0
- package/fixtures/v1/report/table.json +46 -0
- package/package.json +14 -4
- package/src/index.ts +231 -0
- package/tokens/v1.json +85 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 STAIx Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,20 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @staix/cli-output
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
CLI output standard v1 for Bun 1.4.4 or later. The package has no runtime dependencies. See [the standard](docs/standard-v1.md) for the output contract.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { Report, resolveColor, streamEnv } from "@staix/cli-output";
|
|
7
|
+
const color = resolveColor("auto", streamEnv(process.stdout.isTTY), "mytool");
|
|
8
|
+
if (color instanceof Error) throw color;
|
|
9
|
+
console.log(new Report(80).section("Checks").bullet("ok", "ready").render(color).join("\n"));
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`Report` is experimental until its API settles. `resolveColor` returns an Error for an invalid flag; decide stdout and stderr separately.
|
|
13
|
+
|
|
14
|
+
## Vendoring tokens and fixtures
|
|
15
|
+
|
|
16
|
+
For a non-Bun implementation, copy `tokens/v1.json` and `fixtures/v1/` from an exact release tag, preserving paths. Record the tag alongside the copies. Verify each vendored file against that tag with `git show <tag>:<path>` and a SHA-256 comparison, and check the complete file list as well as the checksums. Run all fixtures in the consumer's tests.
|
|
17
|
+
|
|
18
|
+
## Versions
|
|
19
|
+
|
|
20
|
+
The standard version is v1. Breaking API or token changes increment the package major version, new roles, markers or functions increment the minor, and fixes increment the patch. Publishing uses npm trusted publishing; the publisher must be registered on npm before a release tag is pushed.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# CLI output standard v1
|
|
2
|
+
|
|
3
|
+
Version 1. A change to normative parts bumps the standard version.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
`dot` already has an output contract: a `Printer` with a fixed blank-line, indent and stream policy (`internal/cli/printer.go`), a semantic marker alphabet (`internal/ui/markers.go`) and one set of style roles (`internal/ui/prompt.go`). Most other CLIs format output ad hoc. Reading `ahub` 0.39.0 on 2026-11-14:
|
|
8
|
+
|
|
9
|
+
- `ahub status` prints about 85 lines with no section titles. Problems (refused agent versions, failed deliveries, unbound memory) sit between plain facts with the same weight and no marker. Peer detail rows repeat the peer name as a key (` claude form tui`, ` claude flow roles ...`).
|
|
10
|
+
- `ahub doctor` prints `ok` / `fail` / `unknown` as words in a LEVEL column, interleaves fails with oks, and on a piped run one long CHECK cell (a profile path) pushes the FINDING column about 130 characters right. There is no summary line, and it exits `0` with four `fail` rows.
|
|
11
|
+
- `ahub help` fits 80 columns but is one long wall: each command form carries a multi-line description at a 34-column indent.
|
|
12
|
+
- Headings, ids and table headings all share one cyan.
|
|
13
|
+
- `ahub task show <missing id>` prints `No task #N` to stdout and exits `0`.
|
|
14
|
+
|
|
15
|
+
What `ahub` already does right and keeps: `--color=auto|always|never`, `NO_COLOR` and `TERM=dumb` (`resolveColor`), terminal-text sanitizing, width-aware wrapping, `--json` on most read commands.
|
|
16
|
+
|
|
17
|
+
Normative parts of this standard: streams and exit codes, color policy, roles, markers, layout grammar, messages and help. Progress and the per-language notes are guidance.
|
|
18
|
+
|
|
19
|
+
## Principles
|
|
20
|
+
|
|
21
|
+
1. Meaning never rides on color alone. Every state has a glyph and a word; color only reinforces them. Output reads correctly with `NO_COLOR=1`, in grayscale and to a screen reader.
|
|
22
|
+
2. Problems first. Anything that needs action is shown before facts, marked, counted, and paired with the exact next command.
|
|
23
|
+
3. One grammar. Header, section, key/value row, bullet row and table look the same in every command and every CLI.
|
|
24
|
+
4. Calm by default. The default view answers "is it OK, and what do I do next". Detail moves behind `--verbose` or a subcommand.
|
|
25
|
+
5. Humans on the terminal, machines on `--json`. Human output may change between versions; `--json` is the stable interface.
|
|
26
|
+
|
|
27
|
+
## Streams and exit codes
|
|
28
|
+
|
|
29
|
+
- stdout: the result the person asked for, including a report's findings, its Attention section and its summary line, and `--json`.
|
|
30
|
+
- stderr: diagnostics about this invocation (errors, warnings about how the command ran, progress). Library or debug logs (for example Go `slog` INFO lines) never reach the terminal by default; they need `--verbose` or a log-level setting.
|
|
31
|
+
- Exit codes: `0` success; `1` the operation failed, a lookup found nothing, or a check found a failure; `2` usage error (unknown command or flag, bad argument); `75` is reserved for "temporary refusal, retry later" (EX_TEMPFAIL, as `dot remote` uses) and used only where a CLI already has that case.
|
|
32
|
+
- A view command (`status`, `list`, `show`) exits `0` when it could produce its view, even if the view lists problems. A check command (`doctor`, `check`, `lint`) exits `1` when any row is a failure; warnings and unknowns do not change the exit code.
|
|
33
|
+
- `--json` on a report command writes one JSON document to stdout and never contains an ANSI escape. Streaming commands may write JSON lines when documented. Documented bounds (for example "the last 1000 events") are allowed; human-output truncation never applies to `--json`. New timestamp fields use ISO 8601 UTC strings; existing fields keep their format.
|
|
34
|
+
|
|
35
|
+
## Color policy
|
|
36
|
+
|
|
37
|
+
Color is decided per stream (stdout and stderr separately), in this order; the first rule that applies wins:
|
|
38
|
+
|
|
39
|
+
| # | Condition | Color |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| 1 | `--color=never` / `--color=always` | off / on |
|
|
42
|
+
| 2 | `NO_COLOR` is set and non-empty | off |
|
|
43
|
+
| 3 | `FORCE_COLOR` is set, non-empty and not `0`; or `CLICOLOR_FORCE` is set, non-empty and not `0` | on |
|
|
44
|
+
| 4 | `FORCE_COLOR=0` or `CLICOLOR=0` | off |
|
|
45
|
+
| 5 | the stream is a TTY and `TERM` is not `dumb` | on |
|
|
46
|
+
| 6 | otherwise | off |
|
|
47
|
+
|
|
48
|
+
- Every command that prints accepts `--color=auto|always|never` (`auto` = rules 2 to 6).
|
|
49
|
+
- `--json` output is never colored, whatever the rules say.
|
|
50
|
+
- Normative colors are the 16 ANSI colors in the role table. They follow the terminal's own theme, so they stay readable on light and dark backgrounds. A CLI may ship an optional truecolor theme (dot's Tokyo Night hex values, below) only behind an explicit setting, and only with a light and a dark variant per role that reaches 4.5:1 contrast on its background (3:1 for `hint`), checked by a test.
|
|
51
|
+
- Bold is reserved for the header, section titles and the status roles (`success`, `warning`, `error`). No background colors.
|
|
52
|
+
|
|
53
|
+
## Semantic roles
|
|
54
|
+
|
|
55
|
+
The roles are the API. Code names a role, never a raw color or SGR code.
|
|
56
|
+
|
|
57
|
+
| Role | Use | ANSI (normative) | Bold | dot hex (optional dark theme) |
|
|
58
|
+
| --- | --- | --- | --- | --- |
|
|
59
|
+
| `header` | report title | blue (34) | yes | `#7AA2F7` |
|
|
60
|
+
| `section` | section titles | magenta (35) | yes | `#BB9AF7` |
|
|
61
|
+
| `key` | key/value labels, table headings | blue (34) | no | `#7AA2F7` |
|
|
62
|
+
| `value` | values, emphasized list items | default foreground | no | default foreground |
|
|
63
|
+
| `success` | done, healthy, enabled | green (32) | yes | `#9ECE6A` |
|
|
64
|
+
| `warning` | attention needed, non-fatal | yellow (33) | yes | `#E0AF68` |
|
|
65
|
+
| `error` | failure, refusal, non-zero exit | red (31) | yes | `#F7768E` |
|
|
66
|
+
| `hint` | secondary text, unset, unknown, timestamps | bright black (90) | no | `#565F89` fails 3:1 on dark backgrounds; a theme must lighten it |
|
|
67
|
+
| `accent` | ids, refs, commands to copy | cyan (36) | no | `#7DCFFF` |
|
|
68
|
+
|
|
69
|
+
- `hint` text is never the only place a fact appears that the person needs; bright black is faint on some themes.
|
|
70
|
+
- A CLI may add identity colors for its own entities (ahub's per-peer palette) and underline for links, as long as they never reuse a status role's meaning.
|
|
71
|
+
|
|
72
|
+
## Marker alphabet
|
|
73
|
+
|
|
74
|
+
Glyphs are semantic; each pairs with one role. Code uses named constants, never inline glyph literals. A bullet row always carries the state word or the finding text beside the marker, so meaning survives without color.
|
|
75
|
+
|
|
76
|
+
| Marker | Glyph | ASCII | Role | Meaning |
|
|
77
|
+
| --- | --- | --- | --- | --- |
|
|
78
|
+
| `ok` | `✓` | `ok` | `success` | exists, succeeded, enabled, healthy |
|
|
79
|
+
| `fail` | `✗` | `x` | `error` | hard failure, refused |
|
|
80
|
+
| `warn` | `⚠` | `!` | `warning` | attention needed, non-fatal |
|
|
81
|
+
| `absent` | `-` | `-` | `hint` | missing or disabled, not a failure |
|
|
82
|
+
| `unknown` | `?` | `?` | `hint` | not measured, not reported |
|
|
83
|
+
| `pending` | `~` | `~` | `hint` | queued, not yet applied, diff |
|
|
84
|
+
| `active` | `*` | `*` | `success` | active or default choice |
|
|
85
|
+
| `next` | `→` | `->` | `accent` | the next step to run |
|
|
86
|
+
|
|
87
|
+
- A CLI may add markers for states of its own, each with a role from the table, a glyph not used above and an ASCII form, listed in its own marker constants.
|
|
88
|
+
- ASCII forms are used when the locale is not UTF-8 (`LC_ALL`, then `LC_CTYPE`, then `LANG`) or with `--ascii`.
|
|
89
|
+
- Width: the marker column is always 2 cells wide, padded with spaces (ASCII `ok` and `->` fill it). East Asian Ambiguous characters are measured as 1 cell (`Bun.stringWidth(s, { ambiguousIsNarrow: true })`, `unicode-width` non-CJK), so Korean and CJK terminals keep the same alignment.
|
|
90
|
+
|
|
91
|
+
## Layout grammar
|
|
92
|
+
|
|
93
|
+
- **Header**: one line, ` <tool> <Report>` in `header`, followed on the same line or the next by one line of context in `hint` (version, pid, endpoint, project path). One per report. Never in `--json`.
|
|
94
|
+
- **Section**: one blank line, then `▸ <Name>` (ASCII `> <Name>`) in `section`, optionally followed by a count in `hint`: `▸ Peers (4 of 10 online)`. No blank line after it.
|
|
95
|
+
- **Key/value row**: two-space indent, `Key:` padded to the widest key in that section, two spaces, value. A key wider than 28 cells wraps its value to the next line at a four-space indent. An empty value is `(unset)` in `hint`. Keys are words, never repeated entity names: under a peer heading write `form`, not `claude form`.
|
|
96
|
+
- **Bullet row**: two-space indent, the 2-cell marker, one space, text: ` ⚠ codex-review 0.169.0 refused`. Nested detail uses four spaces; a next step is ` → ahub agents trust codex-review 0.169.0`.
|
|
97
|
+
- **Table**: headings uppercase in `key`, two-space gutter, no borders. One flexible column (the free text) wraps; id, state, count and time columns never wrap. Every non-flexible text column is capped at 32 cells whether or not the output wraps, so one long cell cannot push the others off; a path longer than its cap shortens in the middle (`~/Library/.../home`), other text wraps inside its column. Empty cells are `-` in `hint`; a column that is `-` on every row is dropped.
|
|
98
|
+
- **Summary line** (check commands): the last line of stdout, `✗ 2 failed ⚠ 3 warnings ✓ 18 ok`, zero counts omitted, unknowns counted as `? 2 unknown`.
|
|
99
|
+
- **Blank lines**: exactly one before each section, none after; never two in a row; no trailing blank line.
|
|
100
|
+
- **Width**: on a TTY, wrap to the real terminal width. On a pipe, wrap only when `COLUMNS` is set; column caps still apply. Human output never truncates without `...` and a way to see the full value (`--json`, `--verbose` or a `show` subcommand).
|
|
101
|
+
|
|
102
|
+
## Messages
|
|
103
|
+
|
|
104
|
+
- Error line (stderr): `<tool>: <what failed>: <why>`. When stderr is a TTY it is prefixed with the `fail` marker (`✗ ahub: ...`); piped stderr keeps the plain form, so scripts and agents that match `<tool>: ` keep working.
|
|
105
|
+
- Next step: when the CLI knows the fix, a second line ` → <command or setting>` (ASCII ` -> `), complete and copyable (`cd` prefix and every value filled in), in `accent`. An error raised by a server or daemon that carries no fix prints no `→` line; the CLI never invents one.
|
|
106
|
+
- Warning (stderr): `<tool>: warning: <what>: <why>`, `warn` marker on a TTY, optional `→` line.
|
|
107
|
+
- Success confirmation (stdout): `✓ <what was done>`; omit it when the output already shows the result.
|
|
108
|
+
- Usage error: the message, then `Usage: <tool> <command> <args>` and `Run '<tool> help <command>' for details.`, exit `2`.
|
|
109
|
+
- Plain English sentences, no emoji, no exclamation marks. Relative times in human output (`47d ago`, `in 5d15h`).
|
|
110
|
+
|
|
111
|
+
## Help
|
|
112
|
+
|
|
113
|
+
- `<tool> help`, `-h` and `--help` print to stdout and exit `0`: command groups, each command as ` <name> <one-line summary>` in two aligned columns, within 80 columns.
|
|
114
|
+
- `<tool> help <command>` shows usage, a short description, each flag with one line, and one or two examples. Long explanations live here, not in the overview.
|
|
115
|
+
- `ahub` lays it out as `▸ Usage` (every form), `▸ Description` (the overview summary), `▸ Flags (N)` (one line per flag: the flag with its value shape as the usage writes it, then what it is for), `▸ Examples` (one or two complete commands, only for a command that takes arguments) and `▸ Details`, which is the long text, every form with its whole description, unchanged, so nothing a form or flag says is lost. A section with nothing to show is omitted.
|
|
116
|
+
- A flag's line says what the flag is for, in one short line (at most 46 cells beside its label, so it fits 80 columns; `--json` and `--color` keep the longer text this standard defines). The words sit in `FLAG_DESCRIPTIONS` in `src/cli/help.ts`, next to the usage text, keyed by the flag or by `<command> <flag>` where one command uses a flag for something else (`--all`); a flag a definition outside that file adds falls back to the forms that take it. `test/help.test.ts` fails a flag of any command with no description, a line over the width, or a table entry that names no flag. A flag's meaning that only the long text states stays in `Details`. Every example is checked against the dispatch table and the command's own usage by `test/help.test.ts`, so it cannot name a command, subcommand or flag that does not exist.
|
|
117
|
+
- A native agent's overview summary is the third element of its `cli.usage` entry in its adapter definition, never a table in the help module.
|
|
118
|
+
- Usage lines use `<required>`, `[optional]`, `a|b` and `...`.
|
|
119
|
+
|
|
120
|
+
## Progress (guidance)
|
|
121
|
+
|
|
122
|
+
- Spinners or progress bars only when stderr is a TTY and color is on; never on a pipe, in CI or with `--json`. Without a TTY, print one line when a long step starts and one when it ends, with its duration. No carriage-return redraws in output that may be logged.
|
|
123
|
+
|
|
124
|
+
## Conformance checks (every CLI)
|
|
125
|
+
|
|
126
|
+
1. A golden test of the main report with color off, and one with `--color=always` asserting the roles map to the ANSI codes above.
|
|
127
|
+
2. `NO_COLOR=1` with `--color=auto` emits no ESC byte; `--json` never contains ESC; `FORCE_COLOR=1` on a pipe emits color.
|
|
128
|
+
3. At 80 columns no line exceeds 80 cells and no id or state column wraps.
|
|
129
|
+
4. A failing command exits non-zero with `<tool>: ` on stderr, and a usage error exits `2`.
|
|
130
|
+
5. `LANG=C` prints the ASCII markers.
|
|
131
|
+
|
|
132
|
+
## Per-language notes (guidance)
|
|
133
|
+
|
|
134
|
+
- Go: lipgloss v2 as dot uses it; lipgloss downsamples colors itself, so define roles with ANSI colors and add a theme only per the color policy. Disable its CLICOLOR handling only if it disagrees with the table above.
|
|
135
|
+
- TypeScript / Bun: a small zero-dependency module (role to SGR map, marker table, color resolution, `paint`). Use `@staix/cli-output` for the shared Bun implementation.
|
|
136
|
+
- Rust: `anstyle` + `anstream`, and clap's `styles()` set to the same roles for help.
|
|
137
|
+
- Python: `rich` or `click.style`, gated by the same policy.
|
|
138
|
+
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"id": "flag-never",
|
|
4
|
+
"flag": "never",
|
|
5
|
+
"env": {
|
|
6
|
+
"isTTY": true,
|
|
7
|
+
"FORCE_COLOR": "1"
|
|
8
|
+
},
|
|
9
|
+
"expected": false
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"id": "flag-always",
|
|
13
|
+
"flag": "always",
|
|
14
|
+
"env": {
|
|
15
|
+
"isTTY": false,
|
|
16
|
+
"NO_COLOR": "1",
|
|
17
|
+
"TERM": "dumb"
|
|
18
|
+
},
|
|
19
|
+
"expected": true
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
"id": "no-color",
|
|
23
|
+
"flag": "auto",
|
|
24
|
+
"env": {
|
|
25
|
+
"isTTY": true,
|
|
26
|
+
"NO_COLOR": "1",
|
|
27
|
+
"FORCE_COLOR": "1"
|
|
28
|
+
},
|
|
29
|
+
"expected": false
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"id": "no-color-empty",
|
|
33
|
+
"env": {
|
|
34
|
+
"isTTY": true,
|
|
35
|
+
"NO_COLOR": ""
|
|
36
|
+
},
|
|
37
|
+
"expected": true
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"id": "force-pipe",
|
|
41
|
+
"env": {
|
|
42
|
+
"isTTY": false,
|
|
43
|
+
"FORCE_COLOR": "1"
|
|
44
|
+
},
|
|
45
|
+
"expected": true
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"id": "clicolor-force-pipe",
|
|
49
|
+
"env": {
|
|
50
|
+
"isTTY": false,
|
|
51
|
+
"CLICOLOR_FORCE": "1"
|
|
52
|
+
},
|
|
53
|
+
"expected": true
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"id": "force-dumb",
|
|
57
|
+
"env": {
|
|
58
|
+
"isTTY": false,
|
|
59
|
+
"TERM": "dumb",
|
|
60
|
+
"FORCE_COLOR": "1"
|
|
61
|
+
},
|
|
62
|
+
"expected": true
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"id": "force-empty",
|
|
66
|
+
"env": {
|
|
67
|
+
"isTTY": false,
|
|
68
|
+
"FORCE_COLOR": ""
|
|
69
|
+
},
|
|
70
|
+
"expected": false
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"id": "force-zero",
|
|
74
|
+
"env": {
|
|
75
|
+
"isTTY": true,
|
|
76
|
+
"FORCE_COLOR": "0"
|
|
77
|
+
},
|
|
78
|
+
"expected": false
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"id": "clicolor-zero",
|
|
82
|
+
"env": {
|
|
83
|
+
"isTTY": true,
|
|
84
|
+
"CLICOLOR": "0"
|
|
85
|
+
},
|
|
86
|
+
"expected": false
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"id": "force-over-zero",
|
|
90
|
+
"env": {
|
|
91
|
+
"isTTY": false,
|
|
92
|
+
"FORCE_COLOR": "0",
|
|
93
|
+
"CLICOLOR_FORCE": "1"
|
|
94
|
+
},
|
|
95
|
+
"expected": true
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"id": "tty",
|
|
99
|
+
"env": {
|
|
100
|
+
"isTTY": true,
|
|
101
|
+
"TERM": "xterm"
|
|
102
|
+
},
|
|
103
|
+
"expected": true
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"id": "dumb",
|
|
107
|
+
"env": {
|
|
108
|
+
"isTTY": true,
|
|
109
|
+
"TERM": "dumb"
|
|
110
|
+
},
|
|
111
|
+
"expected": false
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"id": "pipe",
|
|
115
|
+
"env": {
|
|
116
|
+
"isTTY": false
|
|
117
|
+
},
|
|
118
|
+
"expected": false
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"id": "no-color-tty",
|
|
122
|
+
"env": {
|
|
123
|
+
"isTTY": true,
|
|
124
|
+
"NO_COLOR": "1"
|
|
125
|
+
},
|
|
126
|
+
"expected": false
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"id": "no-color-clicolor-force",
|
|
130
|
+
"env": {
|
|
131
|
+
"isTTY": false,
|
|
132
|
+
"NO_COLOR": "1",
|
|
133
|
+
"CLICOLOR_FORCE": "1"
|
|
134
|
+
},
|
|
135
|
+
"expected": false
|
|
136
|
+
},
|
|
137
|
+
{
|
|
138
|
+
"id": "force-true",
|
|
139
|
+
"env": {
|
|
140
|
+
"isTTY": false,
|
|
141
|
+
"FORCE_COLOR": "true"
|
|
142
|
+
},
|
|
143
|
+
"expected": true
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
"id": "clicolor-force-zero",
|
|
147
|
+
"env": {
|
|
148
|
+
"isTTY": false,
|
|
149
|
+
"CLICOLOR_FORCE": "0"
|
|
150
|
+
},
|
|
151
|
+
"expected": false
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
"id": "clicolor-one",
|
|
155
|
+
"env": {
|
|
156
|
+
"isTTY": true,
|
|
157
|
+
"CLICOLOR": "1"
|
|
158
|
+
},
|
|
159
|
+
"expected": true
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
"id": "tty-no-term",
|
|
163
|
+
"env": {
|
|
164
|
+
"isTTY": true
|
|
165
|
+
},
|
|
166
|
+
"expected": true
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
"id": "auto-pipe",
|
|
170
|
+
"flag": "auto",
|
|
171
|
+
"env": {
|
|
172
|
+
"isTTY": false,
|
|
173
|
+
"TERM": "xterm"
|
|
174
|
+
},
|
|
175
|
+
"expected": false
|
|
176
|
+
},
|
|
177
|
+
{
|
|
178
|
+
"id": "invalid-rainbow",
|
|
179
|
+
"flag": "rainbow",
|
|
180
|
+
"env": {
|
|
181
|
+
"isTTY": true
|
|
182
|
+
},
|
|
183
|
+
"tool": "tool",
|
|
184
|
+
"expectedError": "usage: tool <command> [--color=auto|always|never]"
|
|
185
|
+
},
|
|
186
|
+
{
|
|
187
|
+
"id": "invalid-empty",
|
|
188
|
+
"flag": "",
|
|
189
|
+
"env": {
|
|
190
|
+
"isTTY": true
|
|
191
|
+
},
|
|
192
|
+
"tool": "tool",
|
|
193
|
+
"expectedError": "usage: tool <command> [--color=auto|always|never]"
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
"id": "invalid-uppercase",
|
|
197
|
+
"flag": "ALWAYS",
|
|
198
|
+
"env": {
|
|
199
|
+
"isTTY": true
|
|
200
|
+
},
|
|
201
|
+
"tool": "tool",
|
|
202
|
+
"expectedError": "usage: tool <command> [--color=auto|always|never]"
|
|
203
|
+
}
|
|
204
|
+
]
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
[
|
|
2
|
+
{"id":"tty","tool":"tool","what":"failed","why":"missing","options":{"tty":true,"next":"tool setup"},"expected":["✗ tool: failed: missing"," → tool setup"]},
|
|
3
|
+
{"id":"pipe","tool":"tool","what":"failed","why":"missing","options":{"tty":false},"expected":["tool: failed: missing"]},
|
|
4
|
+
{"id":"ascii","tool":"tool","what":"failed","why":"missing","options":{"tty":true,"ascii":true,"next":"tool setup"},"expected":["x tool: failed: missing"," -> tool setup"]}
|
|
5
|
+
]
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
[
|
|
2
|
+
{"id":"ok","name":"ok","utf8":"✓ ","ascii":"ok"},
|
|
3
|
+
{"id":"fail","name":"fail","utf8":"✗ ","ascii":"x "},
|
|
4
|
+
{"id":"warn","name":"warn","utf8":"⚠ ","ascii":"! "},
|
|
5
|
+
{"id":"absent","name":"absent","utf8":"- ","ascii":"- "},
|
|
6
|
+
{"id":"unknown","name":"unknown","utf8":"? ","ascii":"? "},
|
|
7
|
+
{"id":"pending","name":"pending","utf8":"~ ","ascii":"~ "},
|
|
8
|
+
{"id":"active","name":"active","utf8":"* ","ascii":"* "},
|
|
9
|
+
{"id":"next","name":"next","utf8":"→ ","ascii":"->"}
|
|
10
|
+
]
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "golden-ascii",
|
|
3
|
+
"input": {
|
|
4
|
+
"columns": 80,
|
|
5
|
+
"ascii": true,
|
|
6
|
+
"operations": [
|
|
7
|
+
{
|
|
8
|
+
"op": "header",
|
|
9
|
+
"tool": "ahub",
|
|
10
|
+
"name": "Check",
|
|
11
|
+
"context": "v0.0.0 pid 1"
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
"op": "section",
|
|
15
|
+
"name": "Attention",
|
|
16
|
+
"count": "2 items"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"op": "bullet",
|
|
20
|
+
"marker": "fail",
|
|
21
|
+
"text": "codex-review 0.169.0 refused"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"op": "next",
|
|
25
|
+
"command": "ahub agents trust codex-review 0.169.0"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"op": "bullet",
|
|
29
|
+
"marker": "warn",
|
|
30
|
+
"text": "memory unbound"
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"op": "section",
|
|
34
|
+
"name": "Hub"
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"op": "kv",
|
|
38
|
+
"rows": [
|
|
39
|
+
[
|
|
40
|
+
"version",
|
|
41
|
+
"0.39.0"
|
|
42
|
+
],
|
|
43
|
+
[
|
|
44
|
+
"pid",
|
|
45
|
+
4242
|
|
46
|
+
],
|
|
47
|
+
[
|
|
48
|
+
"endpoint",
|
|
49
|
+
""
|
|
50
|
+
],
|
|
51
|
+
[
|
|
52
|
+
"a very long key that is wider than twenty eight cells",
|
|
53
|
+
"value"
|
|
54
|
+
]
|
|
55
|
+
]
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"op": "section",
|
|
59
|
+
"name": "Checks"
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"op": "bullet",
|
|
63
|
+
"marker": "ok",
|
|
64
|
+
"text": "tools: git found"
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"op": "bullet",
|
|
68
|
+
"marker": "absent",
|
|
69
|
+
"text": "optional model not configured"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"op": "bullet",
|
|
73
|
+
"marker": "unknown",
|
|
74
|
+
"text": "quota not reported"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"op": "summary",
|
|
78
|
+
"counts": {
|
|
79
|
+
"failed": 1,
|
|
80
|
+
"warnings": 1,
|
|
81
|
+
"unknown": 1,
|
|
82
|
+
"ok": 3
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
]
|
|
86
|
+
},
|
|
87
|
+
"plain": [
|
|
88
|
+
" ahub Check v0.0.0 pid 1",
|
|
89
|
+
"",
|
|
90
|
+
"> Attention (2 items)",
|
|
91
|
+
" x codex-review 0.169.0 refused",
|
|
92
|
+
" -> ahub agents trust codex-review 0.169.0",
|
|
93
|
+
" ! memory unbound",
|
|
94
|
+
"",
|
|
95
|
+
"> Hub",
|
|
96
|
+
" version: 0.39.0",
|
|
97
|
+
" pid: 4242",
|
|
98
|
+
" endpoint: (unset)",
|
|
99
|
+
" a very long key that is wider than twenty eight cells:",
|
|
100
|
+
" value",
|
|
101
|
+
"",
|
|
102
|
+
"> Checks",
|
|
103
|
+
" ok tools: git found",
|
|
104
|
+
" - optional model not configured",
|
|
105
|
+
" ? quota not reported",
|
|
106
|
+
"",
|
|
107
|
+
"x 1 failed ! 1 warning ? 1 unknown ok 3 ok"
|
|
108
|
+
],
|
|
109
|
+
"colored": [
|
|
110
|
+
"\u001b[1;34m ahub Check\u001b[0m\u001b[90m v0.0.0 pid 1\u001b[0m",
|
|
111
|
+
"",
|
|
112
|
+
"\u001b[1;35m> Attention\u001b[0m\u001b[90m (2 items)\u001b[0m",
|
|
113
|
+
" \u001b[1;31mx \u001b[0m codex-review 0.169.0 refused",
|
|
114
|
+
" \u001b[36m-> ahub agents trust codex-review 0.169.0\u001b[0m",
|
|
115
|
+
" \u001b[1;33m! \u001b[0m memory unbound",
|
|
116
|
+
"",
|
|
117
|
+
"\u001b[1;35m> Hub\u001b[0m",
|
|
118
|
+
" \u001b[34mversion:\u001b[0m 0.39.0",
|
|
119
|
+
" \u001b[34mpid:\u001b[0m 4242",
|
|
120
|
+
" \u001b[34mendpoint:\u001b[0m \u001b[90m(unset)\u001b[0m",
|
|
121
|
+
"\u001b[34m a very long key that is wider than twenty eight cells:\u001b[0m",
|
|
122
|
+
" value",
|
|
123
|
+
"",
|
|
124
|
+
"\u001b[1;35m> Checks\u001b[0m",
|
|
125
|
+
" \u001b[1;32mok\u001b[0m tools: git found",
|
|
126
|
+
" \u001b[90m- \u001b[0m optional model not configured",
|
|
127
|
+
" \u001b[90m? \u001b[0m quota not reported",
|
|
128
|
+
"",
|
|
129
|
+
"\u001b[1;31mx 1 failed\u001b[0m \u001b[1;33m! 1 warning\u001b[0m \u001b[90m? 1 unknown\u001b[0m \u001b[1;32mok 3 ok\u001b[0m"
|
|
130
|
+
]
|
|
131
|
+
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "golden",
|
|
3
|
+
"input": {
|
|
4
|
+
"columns": 80,
|
|
5
|
+
"ascii": false,
|
|
6
|
+
"operations": [
|
|
7
|
+
{
|
|
8
|
+
"op": "header",
|
|
9
|
+
"tool": "ahub",
|
|
10
|
+
"name": "Check",
|
|
11
|
+
"context": "v0.0.0 pid 1"
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
"op": "section",
|
|
15
|
+
"name": "Attention",
|
|
16
|
+
"count": "2 items"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"op": "bullet",
|
|
20
|
+
"marker": "fail",
|
|
21
|
+
"text": "codex-review 0.169.0 refused"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"op": "next",
|
|
25
|
+
"command": "ahub agents trust codex-review 0.169.0"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"op": "bullet",
|
|
29
|
+
"marker": "warn",
|
|
30
|
+
"text": "memory unbound"
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"op": "section",
|
|
34
|
+
"name": "Hub"
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"op": "kv",
|
|
38
|
+
"rows": [
|
|
39
|
+
[
|
|
40
|
+
"version",
|
|
41
|
+
"0.39.0"
|
|
42
|
+
],
|
|
43
|
+
[
|
|
44
|
+
"pid",
|
|
45
|
+
4242
|
|
46
|
+
],
|
|
47
|
+
[
|
|
48
|
+
"endpoint",
|
|
49
|
+
""
|
|
50
|
+
],
|
|
51
|
+
[
|
|
52
|
+
"a very long key that is wider than twenty eight cells",
|
|
53
|
+
"value"
|
|
54
|
+
]
|
|
55
|
+
]
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"op": "section",
|
|
59
|
+
"name": "Checks"
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"op": "bullet",
|
|
63
|
+
"marker": "ok",
|
|
64
|
+
"text": "tools: git found"
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"op": "bullet",
|
|
68
|
+
"marker": "absent",
|
|
69
|
+
"text": "optional model not configured"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"op": "bullet",
|
|
73
|
+
"marker": "unknown",
|
|
74
|
+
"text": "quota not reported"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"op": "summary",
|
|
78
|
+
"counts": {
|
|
79
|
+
"failed": 1,
|
|
80
|
+
"warnings": 1,
|
|
81
|
+
"unknown": 1,
|
|
82
|
+
"ok": 3
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
]
|
|
86
|
+
},
|
|
87
|
+
"plain": [
|
|
88
|
+
" ahub Check v0.0.0 pid 1",
|
|
89
|
+
"",
|
|
90
|
+
"▸ Attention (2 items)",
|
|
91
|
+
" ✗ codex-review 0.169.0 refused",
|
|
92
|
+
" → ahub agents trust codex-review 0.169.0",
|
|
93
|
+
" ⚠ memory unbound",
|
|
94
|
+
"",
|
|
95
|
+
"▸ Hub",
|
|
96
|
+
" version: 0.39.0",
|
|
97
|
+
" pid: 4242",
|
|
98
|
+
" endpoint: (unset)",
|
|
99
|
+
" a very long key that is wider than twenty eight cells:",
|
|
100
|
+
" value",
|
|
101
|
+
"",
|
|
102
|
+
"▸ Checks",
|
|
103
|
+
" ✓ tools: git found",
|
|
104
|
+
" - optional model not configured",
|
|
105
|
+
" ? quota not reported",
|
|
106
|
+
"",
|
|
107
|
+
"✗ 1 failed ⚠ 1 warning ? 1 unknown ✓ 3 ok"
|
|
108
|
+
],
|
|
109
|
+
"colored": [
|
|
110
|
+
"\u001b[1;34m ahub Check\u001b[0m\u001b[90m v0.0.0 pid 1\u001b[0m",
|
|
111
|
+
"",
|
|
112
|
+
"\u001b[1;35m▸ Attention\u001b[0m\u001b[90m (2 items)\u001b[0m",
|
|
113
|
+
" \u001b[1;31m✗ \u001b[0m codex-review 0.169.0 refused",
|
|
114
|
+
" \u001b[36m→ ahub agents trust codex-review 0.169.0\u001b[0m",
|
|
115
|
+
" \u001b[1;33m⚠ \u001b[0m memory unbound",
|
|
116
|
+
"",
|
|
117
|
+
"\u001b[1;35m▸ Hub\u001b[0m",
|
|
118
|
+
" \u001b[34mversion:\u001b[0m 0.39.0",
|
|
119
|
+
" \u001b[34mpid:\u001b[0m 4242",
|
|
120
|
+
" \u001b[34mendpoint:\u001b[0m \u001b[90m(unset)\u001b[0m",
|
|
121
|
+
"\u001b[34m a very long key that is wider than twenty eight cells:\u001b[0m",
|
|
122
|
+
" value",
|
|
123
|
+
"",
|
|
124
|
+
"\u001b[1;35m▸ Checks\u001b[0m",
|
|
125
|
+
" \u001b[1;32m✓ \u001b[0m tools: git found",
|
|
126
|
+
" \u001b[90m- \u001b[0m optional model not configured",
|
|
127
|
+
" \u001b[90m? \u001b[0m quota not reported",
|
|
128
|
+
"",
|
|
129
|
+
"\u001b[1;31m✗ 1 failed\u001b[0m \u001b[1;33m⚠ 1 warning\u001b[0m \u001b[90m? 1 unknown\u001b[0m \u001b[1;32m✓ 3 ok\u001b[0m"
|
|
130
|
+
]
|
|
131
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "table",
|
|
3
|
+
"input": {
|
|
4
|
+
"columns": 60,
|
|
5
|
+
"ascii": false,
|
|
6
|
+
"operations": [
|
|
7
|
+
{
|
|
8
|
+
"op": "section",
|
|
9
|
+
"name": "Results"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"op": "table",
|
|
13
|
+
"head": [
|
|
14
|
+
"id",
|
|
15
|
+
"path",
|
|
16
|
+
"finding"
|
|
17
|
+
],
|
|
18
|
+
"rows": [
|
|
19
|
+
[
|
|
20
|
+
"12",
|
|
21
|
+
"/some/path",
|
|
22
|
+
"ready"
|
|
23
|
+
],
|
|
24
|
+
[
|
|
25
|
+
"13",
|
|
26
|
+
"",
|
|
27
|
+
"needs attention"
|
|
28
|
+
]
|
|
29
|
+
],
|
|
30
|
+
"flexible": 2
|
|
31
|
+
}
|
|
32
|
+
]
|
|
33
|
+
},
|
|
34
|
+
"plain": [
|
|
35
|
+
"▸ Results",
|
|
36
|
+
" ID PATH FINDING",
|
|
37
|
+
" 12 /some/path ready",
|
|
38
|
+
" 13 - needs attention"
|
|
39
|
+
],
|
|
40
|
+
"colored": [
|
|
41
|
+
"\u001b[1;35m▸ Results\u001b[0m",
|
|
42
|
+
" \u001b[34mID\u001b[0m \u001b[34mPATH \u001b[0m \u001b[34mFINDING\u001b[0m",
|
|
43
|
+
" 12 /some/path ready",
|
|
44
|
+
" 13 \u001b[90m- \u001b[0m needs attention"
|
|
45
|
+
]
|
|
46
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@staix/cli-output",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
}
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "CLI output standard v1 for Bun",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"repository": { "type": "git", "url": "git+https://github.com/STAIxBWLB/cli-output.git" },
|
|
7
|
+
"exports": "./src/index.ts",
|
|
8
|
+
"types": "./src/index.ts",
|
|
9
|
+
"files": ["src", "docs/standard-v1.md", "tokens/v1.json", "fixtures/v1", "README.md", "LICENSE"],
|
|
10
|
+
"engines": { "bun": ">=1.4.4" },
|
|
11
|
+
"cliOutputStandard": "v1",
|
|
12
|
+
"scripts": { "test": "bun test", "typecheck": "tsc --noEmit", "tokens": "bun scripts/tokens.ts", "tokens:check": "bun scripts/tokens.ts --check" },
|
|
13
|
+
"devDependencies": { "@types/bun": "1.4.4", "typescript": "5.9.3" },
|
|
14
|
+
"publishConfig": { "access": "public" },
|
|
15
|
+
"license": "MIT"
|
|
16
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
// CLI output standard v1: semantic roles, markers, color, text and layout.
|
|
2
|
+
// Human-output code names a role or a marker, never an SGR code or a glyph literal.
|
|
3
|
+
/**
|
|
4
|
+
* The nine semantic roles of CLI output standard v1 on the 16 ANSI colors, so a terminal theme decides the shades. Code names a role,
|
|
5
|
+
* never an SGR code. `value` is the
|
|
6
|
+
* default foreground and carries no SGR. Bold is only for `header`, `section` and the three status roles; no backgrounds.
|
|
7
|
+
*/
|
|
8
|
+
/** End of every painted span. */
|
|
9
|
+
export const SGR_RESET = "\x1b[0m";
|
|
10
|
+
export type Role = "header" | "section" | "key" | "value" | "success" | "warning" | "error" | "hint" | "accent";
|
|
11
|
+
export const ROLE_SGR: Readonly<Record<Role, string>> = Object.freeze({
|
|
12
|
+
header: "\x1b[1;34m", section: "\x1b[1;35m", key: "\x1b[34m", value: "", success: "\x1b[1;32m", warning: "\x1b[1;33m", error: "\x1b[1;31m", hint: "\x1b[90m", accent: "\x1b[36m",
|
|
13
|
+
});
|
|
14
|
+
export const MARKER_NAMES = ["ok", "fail", "warn", "absent", "unknown", "pending", "active", "next"] as const;
|
|
15
|
+
export type MarkerName = (typeof MARKER_NAMES)[number];
|
|
16
|
+
/** Semantic glyphs, each with its ASCII form and the one role that colors it. Code names a marker, never a glyph literal. */
|
|
17
|
+
export const MARKERS: Readonly<Record<MarkerName, { glyph: string; ascii: string; role: Role }>> = Object.freeze({
|
|
18
|
+
ok: { glyph: "✓", ascii: "ok", role: "success" }, fail: { glyph: "✗", ascii: "x", role: "error" }, warn: { glyph: "⚠", ascii: "!", role: "warning" },
|
|
19
|
+
absent: { glyph: "-", ascii: "-", role: "hint" }, unknown: { glyph: "?", ascii: "?", role: "hint" }, pending: { glyph: "~", ascii: "~", role: "hint" },
|
|
20
|
+
active: { glyph: "*", ascii: "*", role: "success" }, next: { glyph: "→", ascii: "->", role: "accent" },
|
|
21
|
+
});
|
|
22
|
+
export const SECTION_MARKER = { glyph: "▸", ascii: ">" } as const;
|
|
23
|
+
export const MARKER_COLUMN = 2;
|
|
24
|
+
/** Cells a string occupies: East Asian Ambiguous characters count as 1, so a Korean or CJK terminal keeps the same alignment. */
|
|
25
|
+
export const cellWidth = (text: string): number => Bun.stringWidth(text, { ambiguousIsNarrow: true });
|
|
26
|
+
/** A marker padded to the 2-cell marker column (ASCII `ok` and `->` fill it). */
|
|
27
|
+
export function markerCell(name: MarkerName, ascii: boolean): string {
|
|
28
|
+
const text = ascii ? MARKERS[name].ascii : MARKERS[name].glyph;
|
|
29
|
+
return text + " ".repeat(Math.max(0, MARKER_COLUMN - cellWidth(text)));
|
|
30
|
+
}
|
|
31
|
+
/** The environment one output stream's color decision reads (`streamEnv` builds it). */
|
|
32
|
+
export interface ColorEnv { isTTY: boolean; TERM?: string; NO_COLOR?: string; FORCE_COLOR?: string; CLICOLOR?: string; CLICOLOR_FORCE?: string }
|
|
33
|
+
/** `isTTY` of the stream that is decided (stdout and stderr are decided separately) plus the color variables of `env`. */
|
|
34
|
+
export function streamEnv(isTTY: boolean, env: Readonly<Record<string, string | undefined>> = process.env): ColorEnv {
|
|
35
|
+
return { isTTY, TERM: env.TERM, NO_COLOR: env.NO_COLOR, FORCE_COLOR: env.FORCE_COLOR, CLICOLOR: env.CLICOLOR, CLICOLOR_FORCE: env.CLICOLOR_FORCE };
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Color for one stream, first rule wins (standard v1): `--color=never|always`; non-empty NO_COLOR off; FORCE_COLOR or CLICOLOR_FORCE
|
|
39
|
+
* non-empty and not `0` on; FORCE_COLOR=0 or CLICOLOR=0 off; a TTY whose TERM is not `dumb` on; otherwise off. `auto` and no flag
|
|
40
|
+
* apply rules 2 to 6. An unknown flag value is a usage error. `--json` is never colored: the caller does not ask.
|
|
41
|
+
*/
|
|
42
|
+
export function resolveColor(flag: string | undefined, env: ColorEnv, tool: string): boolean | Error {
|
|
43
|
+
if (flag === "always") return true;
|
|
44
|
+
if (flag === "never") return false;
|
|
45
|
+
if (flag !== undefined && flag !== "auto") return new Error(`usage: ${tool} <command> [--color=auto|always|never]`);
|
|
46
|
+
if (env.NO_COLOR) return false;
|
|
47
|
+
if ((env.FORCE_COLOR && env.FORCE_COLOR !== "0") || (env.CLICOLOR_FORCE && env.CLICOLOR_FORCE !== "0")) return true;
|
|
48
|
+
if (env.FORCE_COLOR === "0" || env.CLICOLOR === "0") return false;
|
|
49
|
+
return env.isTTY && env.TERM !== "dumb";
|
|
50
|
+
}
|
|
51
|
+
/** ASCII markers when `--ascii` is given or the locale (`LC_ALL`, then `LC_CTYPE`, then `LANG`) is not UTF-8. */
|
|
52
|
+
export function asciiMarkers(env: Readonly<Record<string, string | undefined>> = process.env, flag = false): boolean {
|
|
53
|
+
return flag || !/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || "");
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function terminalText(value: unknown): string {
|
|
57
|
+
return String(value ?? "")
|
|
58
|
+
.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)/g, "")
|
|
59
|
+
.replace(/\x1b[P_X^][\s\S]*?(?:\x1b\\|$)/g, "")
|
|
60
|
+
.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
|
|
61
|
+
.replace(/\x1b[^\n]?/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface Span { text: string; role?: Role }
|
|
65
|
+
export function paint(spans: readonly Span[], color: boolean): string {
|
|
66
|
+
return spans.map(span => { const text = terminalText(span.text); const sgr = span.role && Object.hasOwn(ROLE_SGR, span.role) ? ROLE_SGR[span.role] : undefined; return color && sgr && text ? sgr + text + SGR_RESET : text; }).join("");
|
|
67
|
+
}
|
|
68
|
+
export class Report {
|
|
69
|
+
private readonly out: Span[][] = [];
|
|
70
|
+
/** `columns` undefined means no wrap width: standard v1 wraps on a pipe only when COLUMNS is set. */
|
|
71
|
+
constructor(readonly columns: number | undefined = undefined, readonly ascii = false) {}
|
|
72
|
+
/** The text as lines at most `room` cells wide, or as one line per source line when there is no wrap width. */
|
|
73
|
+
private fit(text: string, room: number): string[] {
|
|
74
|
+
return this.columns === undefined ? terminalText(text).split("\n").map(line => line.replace(/\t/g, " ")) : wrap(text, Math.max(10, room), 0);
|
|
75
|
+
}
|
|
76
|
+
private push(line: Span[]) { this.out.push(line); }
|
|
77
|
+
/** ` <tool> <Report>` in `header`, then one line of context in `hint` on the same line. At most one per report. */
|
|
78
|
+
header(tool: string, name: string, context?: string): this {
|
|
79
|
+
this.push([{ text: ` ${tool} ${name}`, role: "header" }, ...(context ? [{ text: ` ${context}`, role: "hint" as const }] : [])]);
|
|
80
|
+
return this;
|
|
81
|
+
}
|
|
82
|
+
/** One blank line, then `▸ <Name>` (ASCII `> <Name>`) in `section`, with an optional count in `hint`. */
|
|
83
|
+
section(name: string, count?: string): this {
|
|
84
|
+
if (this.out.length && this.out.at(-1)!.length) this.push([]);
|
|
85
|
+
this.push([{ text: `${this.ascii ? SECTION_MARKER.ascii : SECTION_MARKER.glyph} ${name}`, role: "section" }, ...(count ? [{ text: ` (${count})`, role: "hint" as const }] : [])]);
|
|
86
|
+
return this;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Key/value rows of one section: two-space indent, `Key:` padded to the widest key, two spaces, value. A key wider than 28 cells
|
|
90
|
+
* puts its value on the next line at a four-space indent. An empty value is `(unset)` in `hint`.
|
|
91
|
+
*/
|
|
92
|
+
kv(rows: readonly (readonly [string, unknown])[], indent = 2): this {
|
|
93
|
+
const keys = rows.map(([key]) => cellWidth(`${terminalText(key)}:`));
|
|
94
|
+
const pad = Math.max(0, ...keys.filter(width => width <= 28));
|
|
95
|
+
for (const [index, [key, raw]] of rows.entries()) {
|
|
96
|
+
const label = `${terminalText(key)}:`, text = terminalText(raw ?? "").trim();
|
|
97
|
+
const value = (line: string): Span => text ? { text: line, role: "value" } : { text: "(unset)", role: "hint" };
|
|
98
|
+
const lead = " ".repeat(indent);
|
|
99
|
+
if (keys[index]! > 28) {
|
|
100
|
+
this.push([{ text: `${lead}${label}`, role: "key" }]);
|
|
101
|
+
for (const line of text ? this.fit(text, (this.columns ?? 0) - indent - 2) : [""]) this.push([{ text: `${lead} ` }, value(line)]);
|
|
102
|
+
continue;
|
|
103
|
+
}
|
|
104
|
+
const gap = " ".repeat(pad - keys[index]! + 2), room = (this.columns ?? 0) - indent - pad - 2;
|
|
105
|
+
const lines = text ? this.fit(text, room) : [""];
|
|
106
|
+
this.push([{ text: lead }, { text: label, role: "key" }, { text: gap }, value(lines[0]!)]);
|
|
107
|
+
for (const line of lines.slice(1)) this.push([{ text: " ".repeat(indent + pad + 2) }, value(line)]);
|
|
108
|
+
}
|
|
109
|
+
return this;
|
|
110
|
+
}
|
|
111
|
+
/** ` <marker> <text>`; a nested detail line uses four spaces. The text carries the state word, so meaning survives without color. */
|
|
112
|
+
bullet(name: MarkerName, text: string, nested = false): this {
|
|
113
|
+
const indent = nested ? " " : " ", lead = indent.length + MARKER_COLUMN + 1;
|
|
114
|
+
const lines = this.fit(text, (this.columns ?? 0) - lead);
|
|
115
|
+
this.push([{ text: indent }, { text: markerCell(name, this.ascii), role: MARKERS[name].role }, { text: " " }, { text: lines[0]! }]);
|
|
116
|
+
for (const line of lines.slice(1)) this.push([{ text: " ".repeat(lead) + line }]);
|
|
117
|
+
return this;
|
|
118
|
+
}
|
|
119
|
+
/** Render a table. The flexible column wraps; other columns are capped at 32 cells. */
|
|
120
|
+
table(head: readonly string[], rows: readonly (readonly string[])[], flexible = head.length - 1): this {
|
|
121
|
+
if (!head.length) return this;
|
|
122
|
+
if (flexible < 0 || flexible >= head.length) throw new RangeError(`flexible column ${flexible} must be between 0 and ${head.length - 1}`);
|
|
123
|
+
const clean = rows.map(row => head.map((_, i) => terminalText(row[i] ?? "").replace(/[\n\t]/g, " ") || "-"));
|
|
124
|
+
const keep = head.map((_, i) => i).filter(i => clean.some(row => row[i] !== "-"));
|
|
125
|
+
if (!keep.length) return this;
|
|
126
|
+
const flexAt = keep.indexOf(flexible);
|
|
127
|
+
const widths = keep.map(i => {
|
|
128
|
+
const natural = Math.max(cellWidth(head[i]!.toUpperCase()), ...clean.map(row => cellWidth(row[i]!)));
|
|
129
|
+
return i === flexible ? natural : Math.min(32, natural);
|
|
130
|
+
});
|
|
131
|
+
if (this.columns !== undefined) {
|
|
132
|
+
const available = Math.max(keep.length, this.columns - 2 - 2 * (keep.length - 1));
|
|
133
|
+
const minimum = flexAt >= 0 ? Math.min(10, Math.max(1, available - (keep.length - 1))) : 1;
|
|
134
|
+
if (flexAt >= 0) widths[flexAt] = Math.max(minimum, Math.min(widths[flexAt]!, available - widths.reduce((sum, width, i) => sum + (i === flexAt ? 0 : width), 0)));
|
|
135
|
+
while (widths.reduce((sum, width) => sum + width, 0) > available) {
|
|
136
|
+
const candidates = widths.map((width, i) => ({width, i})).filter(({width, i}) => width > (i === flexAt ? minimum : 1)).sort((a, b) => b.width - a.width);
|
|
137
|
+
if (!candidates.length) break;
|
|
138
|
+
widths[candidates[0]!.i]!--;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
const pad = (text: string, width: number) => text + " ".repeat(Math.max(0, width - cellWidth(text)));
|
|
142
|
+
const headings = keep.map((i, n) => wrap(head[i]!.toUpperCase(), widths[n]!, 0));
|
|
143
|
+
for (let line = 0; line < Math.max(...headings.map(cell => cell.length)); line++) {
|
|
144
|
+
this.push([{ text: " " }, ...headings.flatMap((cell, n) => [{ text: n === keep.length - 1 ? (cell[line] ?? "") : pad(cell[line] ?? "", widths[n]!), role: "key" as const }, ...(n < keep.length - 1 ? [{ text: " " }] : [])])]);
|
|
145
|
+
}
|
|
146
|
+
for (const row of clean) {
|
|
147
|
+
const cells = keep.map((i, n) => {
|
|
148
|
+
const value = row[i]!, width = Math.max(1, widths[n]!);
|
|
149
|
+
if (i !== flexible && value.includes("/") && cellWidth(value) > width && width > 3) {
|
|
150
|
+
let left = "", right = "";
|
|
151
|
+
const chars = [...value];
|
|
152
|
+
while (chars.length && cellWidth(left) < Math.floor((width - 3) / 2)) left += chars.shift();
|
|
153
|
+
while (chars.length && cellWidth(left + "..." + chars.at(-1) + right) <= width) right = chars.pop() + right;
|
|
154
|
+
return [left + "..." + right];
|
|
155
|
+
}
|
|
156
|
+
return wrap(value, width, 0);
|
|
157
|
+
});
|
|
158
|
+
const height = Math.max(...cells.map(cell => cell.length));
|
|
159
|
+
for (let line = 0; line < height; line++) {
|
|
160
|
+
const spans: Span[] = [{ text: " " }];
|
|
161
|
+
for (let n = 0; n < keep.length; n++) {
|
|
162
|
+
const value = cells[n]![line] ?? "";
|
|
163
|
+
spans.push({ text: n === keep.length - 1 ? value : pad(value, widths[n]!), ...(value === "-" ? { role: "hint" as const } : {}) });
|
|
164
|
+
if (n < keep.length - 1) spans.push({ text: " " });
|
|
165
|
+
}
|
|
166
|
+
this.push(spans);
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return this;
|
|
170
|
+
}
|
|
171
|
+
/** Lines another renderer built (a table), placed as they are. A section's blank line is still added by `section()`. */
|
|
172
|
+
append(lines: readonly Span[][]): this { for (const line of lines) this.push([...line]); return this; }
|
|
173
|
+
/** A free line in one role, indented two cells (a pointer to more detail, a note). */
|
|
174
|
+
note(text: string, role: Role = "hint"): this {
|
|
175
|
+
for (const line of this.fit(text, (this.columns ?? 0) - 2)) this.push([{ text: " " }, { text: line, role }]);
|
|
176
|
+
return this;
|
|
177
|
+
}
|
|
178
|
+
/** ` → <command>` in `accent`: complete and copyable, never shortened. */
|
|
179
|
+
next(command: string): this {
|
|
180
|
+
this.push([{ text: " " }, { text: `${markerCell("next", this.ascii)} ${terminalText(command)}`, role: "accent" }]);
|
|
181
|
+
return this;
|
|
182
|
+
}
|
|
183
|
+
/** The last line of a check command: `✗ 2 failed ⚠ 3 warnings ✓ 18 ok`, zero counts omitted, unknowns as `? 2 unknown`. */
|
|
184
|
+
summary(counts: { failed?: number; warnings?: number; unknown?: number; ok?: number }): this {
|
|
185
|
+
const parts: Span[] = [];
|
|
186
|
+
const add = (n: number | undefined, name: MarkerName, word: string) => {
|
|
187
|
+
if (!n) return;
|
|
188
|
+
if (parts.length) parts.push({ text: " " });
|
|
189
|
+
parts.push({ text: `${this.ascii ? MARKERS[name].ascii : MARKERS[name].glyph} ${n} ${word}`, role: MARKERS[name].role });
|
|
190
|
+
};
|
|
191
|
+
add(counts.failed, "fail", "failed"); add(counts.warnings, "warn", counts.warnings === 1 ? "warning" : "warnings"); add(counts.unknown, "unknown", "unknown"); add(counts.ok, "ok", "ok");
|
|
192
|
+
if (parts.length) { if (this.out.length) this.push([]); this.push(parts); }
|
|
193
|
+
return this;
|
|
194
|
+
}
|
|
195
|
+
lines(): Span[][] { return this.out.map(line => line.map(item => ({ ...item }))); }
|
|
196
|
+
/** The report as text: one painted string per line, no trailing blank line. */
|
|
197
|
+
render(color: boolean): string[] { return this.out.map(line => paint(line, color)); }
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
export function wrap(value: unknown, columns: number, hang = 4): string[] {
|
|
201
|
+
const lines: string[] = [];
|
|
202
|
+
const half = Math.floor(columns / 2);
|
|
203
|
+
const width = cellWidth;
|
|
204
|
+
for (const part of terminalText(value).replace(/\t/g, " ").split("\n")) {
|
|
205
|
+
const indent = /^\s*/.exec(part)![0];
|
|
206
|
+
const lead = Math.min(cellWidth(indent), half);
|
|
207
|
+
const pad = " ".repeat(Math.min(lead + hang, half));
|
|
208
|
+
const first = lines.length;
|
|
209
|
+
let start = " ".repeat(lead);
|
|
210
|
+
let line = start;
|
|
211
|
+
const push = () => { lines.push(line.trimEnd()); line = start = pad; };
|
|
212
|
+
for (const token of part.slice(indent.length).match(/\s+|\S+/g) ?? []) {
|
|
213
|
+
if (width(line + token) <= columns) { line += token; continue; }
|
|
214
|
+
if (line !== start) push();
|
|
215
|
+
if (/^\s/.test(token)) continue;
|
|
216
|
+
for (const char of token) {
|
|
217
|
+
if (line !== start && width(line + char) > columns) push();
|
|
218
|
+
line += char;
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
if (line !== start || lines.length === first) lines.push(line.trimEnd());
|
|
222
|
+
}
|
|
223
|
+
return lines;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
export const EXIT = Object.freeze({ ok: 0, fail: 1, usage: 2, tempfail: 75 } as const);
|
|
227
|
+
export function errorLine(tool: string, what: string, why: string, options: { next?: string; tty: boolean; ascii?: boolean }): string[] {
|
|
228
|
+
const message = `${terminalText(tool)}: ${terminalText(what)}${why ? `: ${terminalText(why)}` : ""}`;
|
|
229
|
+
const first = options.tty ? `${options.ascii ? MARKERS.fail.ascii : MARKERS.fail.glyph} ${message}` : message;
|
|
230
|
+
return options.next ? [first, ` ${options.ascii ? MARKERS.next.ascii : MARKERS.next.glyph} ${terminalText(options.next)}`] : [first];
|
|
231
|
+
}
|
package/tokens/v1.json
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
{
|
|
2
|
+
"standard": "v1",
|
|
3
|
+
"roles": {
|
|
4
|
+
"header": "1;34",
|
|
5
|
+
"section": "1;35",
|
|
6
|
+
"key": "34",
|
|
7
|
+
"value": "",
|
|
8
|
+
"success": "1;32",
|
|
9
|
+
"warning": "1;33",
|
|
10
|
+
"error": "1;31",
|
|
11
|
+
"hint": "90",
|
|
12
|
+
"accent": "36"
|
|
13
|
+
},
|
|
14
|
+
"markers": {
|
|
15
|
+
"ok": {
|
|
16
|
+
"glyph": "✓",
|
|
17
|
+
"ascii": "ok",
|
|
18
|
+
"role": "success",
|
|
19
|
+
"width": 1,
|
|
20
|
+
"asciiWidth": 2
|
|
21
|
+
},
|
|
22
|
+
"fail": {
|
|
23
|
+
"glyph": "✗",
|
|
24
|
+
"ascii": "x",
|
|
25
|
+
"role": "error",
|
|
26
|
+
"width": 1,
|
|
27
|
+
"asciiWidth": 1
|
|
28
|
+
},
|
|
29
|
+
"warn": {
|
|
30
|
+
"glyph": "⚠",
|
|
31
|
+
"ascii": "!",
|
|
32
|
+
"role": "warning",
|
|
33
|
+
"width": 1,
|
|
34
|
+
"asciiWidth": 1
|
|
35
|
+
},
|
|
36
|
+
"absent": {
|
|
37
|
+
"glyph": "-",
|
|
38
|
+
"ascii": "-",
|
|
39
|
+
"role": "hint",
|
|
40
|
+
"width": 1,
|
|
41
|
+
"asciiWidth": 1
|
|
42
|
+
},
|
|
43
|
+
"unknown": {
|
|
44
|
+
"glyph": "?",
|
|
45
|
+
"ascii": "?",
|
|
46
|
+
"role": "hint",
|
|
47
|
+
"width": 1,
|
|
48
|
+
"asciiWidth": 1
|
|
49
|
+
},
|
|
50
|
+
"pending": {
|
|
51
|
+
"glyph": "~",
|
|
52
|
+
"ascii": "~",
|
|
53
|
+
"role": "hint",
|
|
54
|
+
"width": 1,
|
|
55
|
+
"asciiWidth": 1
|
|
56
|
+
},
|
|
57
|
+
"active": {
|
|
58
|
+
"glyph": "*",
|
|
59
|
+
"ascii": "*",
|
|
60
|
+
"role": "success",
|
|
61
|
+
"width": 1,
|
|
62
|
+
"asciiWidth": 1
|
|
63
|
+
},
|
|
64
|
+
"next": {
|
|
65
|
+
"glyph": "→",
|
|
66
|
+
"ascii": "->",
|
|
67
|
+
"role": "accent",
|
|
68
|
+
"width": 1,
|
|
69
|
+
"asciiWidth": 2
|
|
70
|
+
}
|
|
71
|
+
},
|
|
72
|
+
"sectionMarker": {
|
|
73
|
+
"glyph": "▸",
|
|
74
|
+
"ascii": ">"
|
|
75
|
+
},
|
|
76
|
+
"markerColumn": 2,
|
|
77
|
+
"colorPrecedence": [
|
|
78
|
+
"flag never or always",
|
|
79
|
+
"non-empty NO_COLOR disables",
|
|
80
|
+
"non-empty FORCE_COLOR or CLICOLOR_FORCE other than 0 enables",
|
|
81
|
+
"FORCE_COLOR=0 or CLICOLOR=0 disables",
|
|
82
|
+
"TTY with TERM other than dumb enables",
|
|
83
|
+
"otherwise disabled"
|
|
84
|
+
]
|
|
85
|
+
}
|