@reqray/cli 0.0.0-stage → 0.1.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/DESIGN.md ADDED
@@ -0,0 +1,350 @@
1
+ # `@reqray/cli` — output specification
2
+
3
+ The terminal client prints the same data the web panel shows, reduced to
4
+ sixteen ANSI colours. Line-oriented: every line survives scrollback, `grep`,
5
+ and a log file. No full-screen frames, no menus, no fills, no emoji.
6
+
7
+ This file is the contract the snapshot tests are written against. Numbers here
8
+ are not suggestions — a change to any of them changes a snapshot, which is the
9
+ point.
10
+
11
+ ## Palette: panel token → ANSI 16
12
+
13
+ The panel is built on `oklch` with four steps of grey. ANSI-16 has one muted
14
+ step, one ordinary and one bright. What was given up is written down.
15
+
16
+ | Panel token | ANSI | Carries | What it cost |
17
+ | --- | --- | --- | --- |
18
+ | `--fg` | 39 default | Row data | Not 37 white: only *default* inherits the reader's theme and stays legible on light and dark alike. |
19
+ | `--fg2` | 37 white | Cache spans | On some themes it nearly merges with default. So it carries exactly one meaning, in one place, where a label sits next to it. |
20
+ | `--fg3` + `--line` | 90 br. black | Labels, units, rules | Two panel steps collapsed into one. What separates a label from a rule is the density of the glyph, not the colour. |
21
+ | `--acc` | 36 cyan | Handler spans, commands | The panel's accent is muted steel; ANSI cyan is far more saturated. Hence the rule: cyan means handler spans and commands that can be copied and run — nothing else. |
22
+ | `--ok` | 32 green | SQL, improvements | Same meaning as the panel. But 2xx is never green: in a stream that would put a green column on every line. |
23
+ | `--warn` | 33 / 93 yellow | Slow, findings | 33 fades to unreadable on some light themes, so yellow is never the only carrier of a fact — there is always a glyph in the gutter beside it. |
24
+ | `--err` | 31 / 91 red | 5xx, regressions | Direct correspondence; the only pair that lost nothing. |
25
+ | — | 34 blue, 35 magenta | unused | Blue goes unreadable on many dark themes and magenta has no counterpart in this data model. Reserved for plugins. |
26
+
27
+ Bright here does not mean "lighter", it means "needs attention": on a light
28
+ terminal theme bright variants render darker and more saturated than the
29
+ ordinary ones. The hierarchy is built on contrast with the background, not on
30
+ lightness, which is why it survives both themes.
31
+
32
+ ## Four rules everything else follows from
33
+
34
+ **Gutter instead of colour.** Two columns at the start of every line carry
35
+ severity as a glyph: empty, `!`, `!!`. Colour duplicates them, never replaces
36
+ them. So `NO_COLOR` loses no distinction and shifts the layout by not one
37
+ character.
38
+
39
+ **Two bright elements per screen.** Bright variants belong to the finding flag
40
+ and to 5xx. A calm stream has no bright glyph at all.
41
+
42
+ **The order things are dropped.** Query string, then middle path segments,
43
+ then the query-count column, then the status column — which is kept for
44
+ non-2xx. Time, method, duration and flags are never truncated: reading the
45
+ stream is built on them.
46
+
47
+ **No fills.** No element sets a background, so the output lands on any theme.
48
+ The single exception is the inverted verdict (reverse video), which takes the
49
+ terminal's own colours and is therefore correct everywhere, monochrome
50
+ included. Reverse is not used by `watch` or `show`.
51
+
52
+ ## `reqray watch` — the stream
53
+
54
+ `tail -f` for requests. One line per request, a fixed column grid, severity in
55
+ the first two columns.
56
+
57
+ ```
58
+ gutter(2) SP time(12) SP method(6) SP status(3) SP path(W) SP SP duration(→7) SP queries(→4) SP flags(≤4)
59
+ ```
60
+
61
+ `→` means right-aligned. Everything else is left-aligned and padded. The fixed
62
+ part is 42 columns plus a flag reserve of 8, and one column is left unused at
63
+ the right edge so a full line never wraps:
64
+
65
+ W = terminal width − 51
66
+
67
+ The head row (`TIME METHOD ST PATH DUR Q FLAGS`) uses the same grid, muted.
68
+
69
+ ### The identifier
70
+
71
+ The grid has no id column, because an id is a handle rather than something to
72
+ read: a dozen characters of noise on every line, in the place the eye scans for
73
+ the path. `--ids` adds it, between the gutter and the time, painted cyan like
74
+ every other string here that can be copied into a command — and its width
75
+ comes out of the path's budget, so nothing else moves.
76
+
77
+ Without it, a row on screen is opened through the question that found it:
78
+ `show --last`, `--last --failed`, `--last --slowest`, `--last --path /orders`.
79
+ A failed request needs neither: its second line already ends in the command.
80
+
81
+ ### Widths
82
+
83
+ Only the path column is flexible. Time, method, duration and flags keep their
84
+ place so that output at 80 and at 200 columns reads the same way.
85
+
86
+ | Terminal width | Dropped | Path column |
87
+ | --- | --- | --- |
88
+ | ≥ 72 | nothing | `width − 51` |
89
+ | 64…71 | queries | `width − 46` |
90
+ | 56…63 | queries, status | `width − 42` |
91
+ | < 56 | — | refuses: one line of explanation, exit 2 |
92
+
93
+ With the status column gone, a non-2xx row prints its code in the flag column
94
+ (`500`, `404`) ahead of any finding flag: the code is the more serious fact and
95
+ the flag is one click away in `show`.
96
+
97
+ Below 72 columns the path floor is 21 characters, which is what the table
98
+ above is derived from.
99
+
100
+ ### Truncating a path
101
+
102
+ Whole segments, never characters: a truncated path stays a valid path and can
103
+ still be recognised. `/api/v2/organizat…` tells the reader nothing.
104
+
105
+ 1. The query string goes first, replaced by `?…`.
106
+ 2. Then middle segments, replaced by a single `…` segment. The first segment
107
+ says which service, the last says which handler; the identifiers in the
108
+ middle are given up first.
109
+ 3. If the leaf alone does not fit, it is cut with a trailing `…`.
110
+
111
+ Both `…` and the `?…` marker are muted: they are metadata the client added,
112
+ not something that was in the request.
113
+
114
+ The first segment is kept as long as the leaf still fits beside it, and the
115
+ tail grows greedily from the right: the leaf says which handler, the first
116
+ says which service, and what goes is the run of identifiers between them.
117
+
118
+ | Path column | Result |
119
+ | --- | --- |
120
+ | 49 | `/api/…/checkout-service/deployments/latest/logs?…` |
121
+ | 29 | `/api/…/latest/logs?…` |
122
+ | 18 | `/api/…/logs?…` |
123
+ | 10 | `/…/logs` |
124
+
125
+ ### Flags
126
+
127
+ One flag per row, from the detector behind the costliest finding, in the
128
+ panel's own words: `N+1`, `SEQ`, `DUP`, `SLOW`. `ERR` for a request that
129
+ failed, `TEST` for one a test issued. `ERR` wins over a finding flag.
130
+
131
+ ### Continuation line
132
+
133
+ The one exception to "one line per request": a request with an exception gets
134
+ a second line with the exception type, the message, the callsite, and the
135
+ `reqray show <id>` that opens it. An exception with neither type nor file would
136
+ send the reader to `show` immediately — cheaper to print it right away.
137
+
138
+ ```
139
+ └ TypeError: Cannot read properties of undefined (reading 'currency')
140
+ services/pricing.js:61 reqray show 9012
141
+ ```
142
+
143
+ ### Reconnecting
144
+
145
+ A dropped stream prints one muted line — not silence, and not a stack trace.
146
+ Backoff doubles from 500 ms to a 10 s ceiling; a restored connection says so.
147
+
148
+ ```
149
+ … connection lost, reconnecting in 2 s (attempt 3)
150
+ … reconnected
151
+ ```
152
+
153
+ ## `reqray show <id>` — one request
154
+
155
+ Waterfall first, then findings, then the response. The order is not arbitrary:
156
+ first where the time went, then what to do about it.
157
+
158
+ ```
159
+ GET /api/orders 200 275ms 09:41:02.184 #8974 from orders.spec.ts:42
160
+
161
+ WATERFALL 15 spans, 2 of them duplicated
162
+ 0ms 69ms 138ms 206ms 275ms
163
+ ├──────────┼──────────┼──────────┼──────────┤
164
+ mw cors ▏ 0.4ms
165
+ fn orders.list ├────────────────────────────────┤ 268ms
166
+ sql 47× SELECT line_items ███████ 41.2ms N+1
167
+ ```
168
+
169
+ ```
170
+ SP SP kind(6) label(28, indented 2 per level) SP bar(cells) SP SP duration(→7) SP badge
171
+ ```
172
+
173
+ The scale and the ruler start at column 37 (`2 + 6 + 28 + 1`). The bar is the
174
+ only flexible column:
175
+
176
+ cells = clamp(width − 55, 12, 60)
177
+
178
+ which gives the 45 cells of the reference mockup at 100 columns. The ruler is
179
+ five ticks with even segments between them; the scale above it prints five
180
+ times — the first left-aligned at the first tick, the last right-aligned at
181
+ the last, the rest centred on theirs. The scale line carries nothing else, so
182
+ it may run past the ruler up to the edge of the terminal; where five times
183
+ would not fit even then it prints three, then two, then the total alone.
184
+
185
+ A span shorter than one cell is drawn as `▏` in its own cell rather than
186
+ disappearing. Losing a span is worse than showing it imprecisely. A handler
187
+ span is drawn as a bracket `├──┤`, not a filled bar: it is a container, not
188
+ work, and must not weigh as much as its contents.
189
+
190
+ Spans belonging to one N+1 finding collapse into a single `47× SELECT …` row,
191
+ exactly as they do in the panel.
192
+
193
+ | Kind | Colour |
194
+ | --- | --- |
195
+ | `mw` middleware | 90 muted, label included |
196
+ | `fn` handler | 36 cyan, bracket |
197
+ | `sql` | 32 green |
198
+ | `http` | 33 yellow |
199
+ | `cache` | 37 white |
200
+
201
+ ### Findings
202
+
203
+ ```
204
+ FINDINGS 3
205
+
206
+ ! N+1 47 identical queries in a loop 41.2ms 15% of total
207
+ SELECT * FROM line_items WHERE order_id = $1
208
+ services/orders.js:118, inside the serializer loop
209
+ fix eager-load line_items with a single IN (…) query
210
+
211
+ dup 2 identical cache reads for one key 0.4ms
212
+ cache.get feature-flags:checkout-v3 middleware/flags.js:14
213
+ ```
214
+
215
+ Two levels. Findings are ordered by cost; **at most the two costliest**, and
216
+ only those costing at least 1 ms, get the loud form: `!` in the gutter, the
217
+ tag in bright yellow, the sample, the callsite, and the fix. Everything else
218
+ gets the quiet form: no gutter, a muted lowercase tag, one line of context.
219
+ Three loud findings on one screen would break the two-bright rule and turn a
220
+ report into an alarm.
221
+
222
+ ### Response
223
+
224
+ ```
225
+ RESPONSE 200 application/json 4.1 KB etag W/"105b-7Yl1dK+8"
226
+ server-timing db;dur=52.1 cache;dur=0.8 ext;dur=214.0
227
+ body {"data":[{"id":8812,"reference":"ORD-2026-8812",…}],"meta":{…}}
228
+
229
+ reqray show 8974 --body the whole response body
230
+ reqray show 8974 --sql all 51 queries with their callsites
231
+ ```
232
+
233
+ The body is one line, cut at the column budget. The trailing commands are
234
+ cyan: truncation without a way out is a dead end, so the escape hatch is
235
+ printed next to what was cut.
236
+
237
+ ### `--sql`
238
+
239
+ ```
240
+ q2 8.6ms 25 rows services/orders.js:96
241
+
242
+ SELECT o.id, o.reference, o.status, o.total_cents, o.currency, o.created_at,
243
+ u.email, u.display_name, a.line1, a.city, a.country_code, COUNT(li.id) AS
244
+ item_count FROM orders o INNER JOIN users u ON u.id = o.user_id LEFT JOIN
245
+ … 4 more lines reqray show 8974 --sql q2 --full
246
+
247
+ ! q3 41.2ms 47 calls services/orders.js:118 N+1
248
+ SELECT * FROM line_items WHERE order_id = $1
249
+ ```
250
+
251
+ SQL is wrapped, not truncated: a path can be recognised from a fragment, a
252
+ query cannot. Wrapping is at the window width with a hanging indent of 7,
253
+ capped at 3 lines; the rest is behind `--sql <ref> --full`. Keywords are cyan
254
+ and literals and placeholders green — the only place in the client where
255
+ colour is applied inside a line rather than to a column.
256
+
257
+ ### Finding one without an id
258
+
259
+ ```
260
+ reqray show --last the one that just finished
261
+ reqray show --last --failed the last one that failed
262
+ reqray show --last --slowest the slowest one recorded
263
+ reqray show --last --path /orders the last one to a path
264
+ ```
265
+
266
+ `--path` here is a substring, not a glob, and the store is what searches: the
267
+ question "the last request whose path contains this" has one true answer,
268
+ where matching a glob in the client would mean "the last one among however
269
+ many rows happened to come back". A `*` typed out of habit is stripped rather
270
+ than refused.
271
+
272
+ ## Empty and unreachable
273
+
274
+ Both states must end in an action rather than a statement.
275
+
276
+ ```
277
+ reqray 0.6.0 watching localhost:3000 pid 41822 ctrl-c to stop
278
+
279
+ collector attached — no requests recorded yet
280
+
281
+ try curl -s localhost:3000/api/orders
282
+ or just reload the application in a browser
283
+
284
+ waiting buffer 500, empty
285
+ ```
286
+
287
+ Empty is not an error: nothing is red, the header is the one a working stream
288
+ prints, and the only coloured element is a command that can be copied. The
289
+ status line mirrors the panel's status bar so the two read as one product.
290
+
291
+ ```
292
+ reqray: cannot reach the collector
293
+
294
+ the panel is served by your app. check that
295
+ 1 reqray is attached reqray({ panel: true }) before the routes
296
+ 2 the app is running and that NODE_ENV is not production
297
+ 3 the address matches REQRAY_URL=http://localhost:3000/_reqray
298
+
299
+ reqray --verbose prints what actually failed
300
+ ```
301
+
302
+ Only the headline is bright. Three numbered hypotheses in order of likelihood
303
+ rather than one hint, with the concrete values on the right in ordinary colour
304
+ — those get copied.
305
+
306
+ The system cause (`fetch failed — connect ECONNREFUSED 127.0.0.1:3000`) is
307
+ printed under `--verbose`, muted, above the hypotheses. It belongs in a bug
308
+ report rather than in the reading, and putting it first would bury the three
309
+ things actually worth checking.
310
+
311
+ ## Degradation
312
+
313
+ **Colour off** when `NO_COLOR` is set, `TERM=dumb`, stdout is not a TTY, or
314
+ `--no-color` is given. Symmetrically `--color=always` for piping into
315
+ `less -R`. One check, in one place; every renderer asks it rather than
316
+ deciding for itself.
317
+
318
+ Without colour the layout is identical, character for character. A 500 is
319
+ carried by five signals with no colour among them: the `!!` gutter, the word
320
+ `ERR`, the code `500`, the magnitude `2.14s`, and the continuation line with
321
+ the exception type.
322
+
323
+ **Unicode off** with `--ascii`, `REQRAY_ASCII=1`, or a locale that is not
324
+ UTF-8. Every substitution is one character wide, so no column moves; the
325
+ ellipsis is three characters and is accounted for in the truncation budget.
326
+
327
+ | Unicode | ASCII | Where |
328
+ | --- | --- | --- |
329
+ | `├─┼─┤` | `+--+--+` | waterfall ruler |
330
+ | `█` | `#` | span bar |
331
+ | `▏` | `\|` | span shorter than one cell |
332
+ | `├──┤` | `[--]` | handler span |
333
+ | `…` | `...` | truncation |
334
+ | `└` | `\_` | continuation line |
335
+ | `×` | `x` | multiplier |
336
+
337
+ No emoji in either mode: their width differs between terminals and breaks the
338
+ columns.
339
+
340
+ ## Exit codes
341
+
342
+ | Code | Meaning |
343
+ | --- | --- |
344
+ | 0 | success |
345
+ | 1 | execution failed, or the collector could not be reached |
346
+ | 2 | bad arguments, or a terminal too narrow to print in |
347
+
348
+ Errors are addressed to a person: what happened, and what to do about it. The
349
+ technical cause is printed under `--verbose` only. Ctrl+C exits cleanly with
350
+ no stack trace.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ruslan Kryklyvyi
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,14 @@
1
- # Temporary Holding Version
1
+ # @reqray/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Reqray from the terminal: a live request stream and a full breakdown of one request.
4
+
5
+ Part of [Reqray](https://github.com/reqray/reqray) — a dev panel and request-inspection tool for
6
+ Node.js. It instruments HTTP, SQL, outgoing calls and cache on its own, shows
7
+ every request as a waterfall, and finds N+1 down to the file and the line.
8
+
9
+ Documentation, screenshots and a demo that runs with one command are in the
10
+ [main README](https://github.com/reqray/reqray#readme).
11
+
12
+ ## License
13
+
14
+ [MIT](https://github.com/reqray/reqray/blob/main/LICENSE)