@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.
@@ -0,0 +1,367 @@
1
+ import { RequestSort, PanelMeta, RequestsResponse, RequestDetail, BaselineResponse, RequestRow } from '@reqray/protocol';
2
+
3
+ /**
4
+ * One run of the client.
5
+ *
6
+ * Separated from the executable so a test can run a whole command — argv in,
7
+ * lines and an exit code out — without a subprocess and without the signal
8
+ * handling that only makes sense around a real process.
9
+ */
10
+ /** The process a run reads and writes. */
11
+ interface Runtime {
12
+ readonly env: NodeJS.ProcessEnv;
13
+ readonly stdout: {
14
+ isTTY?: boolean;
15
+ columns?: number;
16
+ write(chunk: string): unknown;
17
+ };
18
+ readonly stderr: {
19
+ write(chunk: string): unknown;
20
+ };
21
+ /** Aborted on Ctrl+C. */
22
+ readonly signal?: AbortSignal;
23
+ }
24
+ /**
25
+ * Runs one command.
26
+ *
27
+ * @returns the exit code. Failures are printed here and never thrown at the
28
+ * caller: an exception reaching a terminal is a stack trace, and a stack
29
+ * trace is what a tool prints when it has nothing useful to say.
30
+ */
31
+ declare function run(argv: readonly string[], runtime: Runtime): Promise<number>;
32
+
33
+ /**
34
+ * The panel API, over HTTP.
35
+ *
36
+ * This client carries no instrumentation and imports no part of `@reqray/core`:
37
+ * it talks to the same endpoints the web panel talks to, and the shapes it
38
+ * receives come from `@reqray/protocol` as types only. A collector reached
39
+ * through an ssh tunnel is an ordinary URL and needs nothing else.
40
+ *
41
+ * Built-in `fetch`, and a hand-rolled reader for the event stream. `undici` is
42
+ * a dependency an `npx` user waits for, and the global `EventSource` cannot
43
+ * set the header a token-protected collector requires.
44
+ */
45
+
46
+ /** Where the panel is, and how to get past its gate. */
47
+ interface ClientOptions {
48
+ /** Base URL of the panel, e.g. `http://localhost:3000/_reqray`. */
49
+ readonly url: string;
50
+ /** Shared secret, for a collector that was started with one. */
51
+ readonly token?: string | null;
52
+ /** Swapped out in tests. */
53
+ readonly fetch?: typeof globalThis.fetch;
54
+ }
55
+ /** What to ask the list for. Mirrors the panel's own query parameters. */
56
+ interface ListQuery {
57
+ readonly limit?: number;
58
+ /** Substring of the method, path, status or query string. */
59
+ readonly query?: string;
60
+ readonly cursor?: string | null;
61
+ readonly minDurationMs?: number;
62
+ readonly methods?: readonly string[];
63
+ readonly statusClasses?: readonly number[];
64
+ readonly onlyFindings?: boolean;
65
+ readonly onlyErrors?: boolean;
66
+ readonly sort?: RequestSort;
67
+ }
68
+ /** What a live stream reports back. */
69
+ interface StreamHandlers {
70
+ /** A request just finished. */
71
+ onRow(row: unknown): void;
72
+ /** Something the reader should know about the connection itself. */
73
+ onNotice(text: string): void;
74
+ /** Aborting it ends the stream and the retry loop with it. */
75
+ readonly signal: AbortSignal;
76
+ /** Swapped out in tests, so backoff costs no wall-clock time. */
77
+ sleep?(ms: number): Promise<void>;
78
+ }
79
+ /** A client for one panel. */
80
+ declare class ReqrayClient {
81
+ #private;
82
+ constructor(options: ClientOptions);
83
+ /** The panel's address, as it was resolved. */
84
+ get url(): string;
85
+ /** What the process behind the panel is. */
86
+ meta(signal?: AbortSignal): Promise<PanelMeta>;
87
+ /** One page of the list. */
88
+ list(query?: ListQuery, signal?: AbortSignal): Promise<RequestsResponse>;
89
+ /** One request, whole. */
90
+ detail(id: string, signal?: AbortSignal): Promise<RequestDetail>;
91
+ /**
92
+ * How the request compares against its route's own history, and whether
93
+ * the process underneath was struggling at the time.
94
+ *
95
+ * Empty when there is nothing to compare against, and empty too when the
96
+ * collector is older than the endpoint: a verdict is worth printing when it
97
+ * is there and worth nothing said when it is not.
98
+ */
99
+ baseline(id: string, signal?: AbortSignal): Promise<BaselineResponse>;
100
+ /** The same, unparsed — what `--json` prints. */
101
+ detailRaw(id: string, signal?: AbortSignal): Promise<string>;
102
+ /**
103
+ * The live feed, until the signal is aborted.
104
+ *
105
+ * A dropped connection is reported and retried with a doubling delay: the
106
+ * application restarting is the common case, and a client that dies with it
107
+ * is a client nobody leaves running.
108
+ */
109
+ stream(handlers: StreamHandlers): Promise<void>;
110
+ }
111
+
112
+ /**
113
+ * Failures, as a person reads them.
114
+ *
115
+ * Every way this client can fail ends in one of these: a headline in plain
116
+ * words, hypotheses about what to do next, and — only under `--verbose` — the
117
+ * technical cause. A stack trace is what a tool prints when it has nothing
118
+ * useful to say.
119
+ */
120
+ /** Exit codes, as documented in DESIGN.md. */
121
+ declare const EXIT_OK = 0;
122
+ /** Something went wrong, including a collector that cannot be reached. */
123
+ declare const EXIT_FAILED = 1;
124
+ /** The arguments, or the terminal, made the command impossible to run. */
125
+ declare const EXIT_USAGE = 2;
126
+ /** A failure with an exit code and something to say about it. */
127
+ declare class CliError extends Error {
128
+ readonly exitCode: number;
129
+ /**
130
+ * Lines printed under the headline: what to check, what to run next.
131
+ *
132
+ * Rendered as given, so they carry their own indentation.
133
+ */
134
+ readonly hints: readonly string[];
135
+ constructor(message: string, options?: {
136
+ exitCode?: number;
137
+ hints?: readonly string[];
138
+ cause?: unknown;
139
+ });
140
+ }
141
+ /** Bad arguments, a missing value, a terminal too narrow to print in. */
142
+ declare class UsageError extends CliError {
143
+ constructor(message: string, hints?: readonly string[]);
144
+ }
145
+ /**
146
+ * The collector did not answer.
147
+ *
148
+ * The three hypotheses are ordered by how often each one turns out to be the
149
+ * answer, and the concrete values sit on the right because they get copied.
150
+ */
151
+ declare class UnreachableError extends CliError {
152
+ constructor(url: string, cause: unknown);
153
+ }
154
+
155
+ /**
156
+ * Narrowing the live stream.
157
+ *
158
+ * The stream endpoint sends every request and takes no parameters, so this is
159
+ * decided here — the same way the web panel narrows its own feed. It is also
160
+ * the only sensible place for it: `--path` is a glob, and a glob is a
161
+ * question about a string, not about a store.
162
+ */
163
+
164
+ /** What `watch` was asked to show. */
165
+ interface StreamFilter {
166
+ readonly slowerThanMs?: number | null;
167
+ /** `404`, `4xx`, `5xx` — codes and classes together. */
168
+ readonly statuses?: readonly string[];
169
+ readonly methods?: readonly string[];
170
+ /** A glob over the path: `*` is any run of characters, `?` is one. */
171
+ readonly path?: string | null;
172
+ readonly findingsOnly?: boolean;
173
+ }
174
+ /** Whether a row belongs on screen. */
175
+ declare function matches(row: RequestRow, filter: StreamFilter): boolean;
176
+
177
+ /**
178
+ * Colour and glyphs, decided once.
179
+ *
180
+ * Every renderer asks the theme rather than reading the environment itself:
181
+ * one place decides whether this output is going to a terminal, a pipe or a
182
+ * CI log, and one place knows what to draw when the font cannot be trusted.
183
+ *
184
+ * Sixteen colours, no backgrounds, no emoji. Colour is a second layer over
185
+ * glyphs that already carry the meaning — turning it off must lose nothing.
186
+ */
187
+ /** What a piece of output means, not what colour it is. */
188
+ type Style =
189
+ /** Coordinates: time, units, rules, column heads. */
190
+ 'dim'
191
+ /** The data itself. */
192
+ | 'plain'
193
+ /** Cache spans — the one thing 37 white carries. */
194
+ | 'faint'
195
+ /** SQL, and improvements. */
196
+ | 'ok'
197
+ /** Slow, and the context around a finding. */
198
+ | 'warn'
199
+ /** A finding. At most two of these on a screen. */
200
+ | 'warnLoud'
201
+ /** 5xx context, regressions. */
202
+ | 'err'
203
+ /** A 500, and the headline of a failure. */
204
+ | 'errLoud'
205
+ /** A handler span, and any command that can be copied and run. */
206
+ | 'cmd'
207
+ /** Reverse video. One verdict, nowhere else. */
208
+ | 'invert';
209
+ /** Things drawn with characters a non-UTF-8 terminal cannot show. */
210
+ type GlyphName = 'barFull' | 'barSliver' | 'bracketOpen' | 'bracketClose' | 'bracketFill' | 'rulerTick' | 'ellipsis' | 'corner' | 'times' | 'none';
211
+ /** How this run draws. */
212
+ interface Theme {
213
+ readonly color: boolean;
214
+ readonly unicode: boolean;
215
+ /** Terminal width in columns. */
216
+ readonly width: number;
217
+ paint(style: Style, text: string): string;
218
+ glyph(name: GlyphName): string;
219
+ }
220
+ /** What the command line asked for, before the environment is consulted. */
221
+ interface ThemeFlags {
222
+ /** `auto` follows the terminal; the other two are the explicit flags. */
223
+ readonly color?: 'auto' | 'always' | 'never';
224
+ readonly ascii?: boolean;
225
+ /** Overrides the detected width. Tests need a stable one. */
226
+ readonly width?: number;
227
+ }
228
+ /** The stream a theme is resolved for. */
229
+ interface OutputStream {
230
+ readonly isTTY?: boolean;
231
+ readonly columns?: number;
232
+ }
233
+ /** Resolves how this run draws, once, at startup. */
234
+ declare function resolveTheme(env: NodeJS.ProcessEnv, stdout: OutputStream, flags?: ThemeFlags): Theme;
235
+ /** A theme for tests and for measuring: no colour, a width that holds still. */
236
+ declare function plainTheme(width?: number, unicode?: boolean): Theme;
237
+
238
+ /**
239
+ * What every command needs before it can do anything.
240
+ *
241
+ * The address of the panel, the token to get past its gate, and how this run
242
+ * draws. Resolved once, in one place, so `watch` and `show` cannot disagree
243
+ * about where the collector is or whether the terminal takes colour.
244
+ */
245
+
246
+ /**
247
+ * Where a locally running application serves its panel.
248
+ *
249
+ * A collector on another machine is an ordinary URL: forward its port over
250
+ * ssh and `--url http://localhost:4300/_reqray` needs nothing else.
251
+ */
252
+ declare const DEFAULT_URL = "http://localhost:3000/_reqray";
253
+ /** Settings shared by every command. */
254
+ interface Globals {
255
+ readonly url: string;
256
+ readonly token: string | null;
257
+ readonly verbose: boolean;
258
+ readonly theme: Theme;
259
+ }
260
+ /**
261
+ * Normalizes a panel address.
262
+ *
263
+ * A bare origin gets the default mount point: someone who types the address
264
+ * of their application means the panel on it, and answering that with a 404
265
+ * from the application's own router would be a puzzle rather than an error.
266
+ */
267
+ declare function normalizeUrl(raw: string): string;
268
+
269
+ /**
270
+ * One request, on one line.
271
+ *
272
+ * The grid is fixed so the eye can hold a vertical: the same fact is always in
273
+ * the same place, and the gutter reserves its two columns even when they are
274
+ * empty, so a `!` appearing does not shift the line under it.
275
+ *
276
+ * Severity is carried by a glyph first and by colour second. Every renderer
277
+ * here paints padded text, never pads painted text — an escape sequence has
278
+ * no width, and measuring one is how columns drift.
279
+ */
280
+
281
+ /** What a stream line may show beyond the fixed grid. */
282
+ interface RowOptions {
283
+ /** Print the identifier `show` takes, so a row on screen can be opened. */
284
+ readonly ids?: boolean;
285
+ }
286
+ /** The column heads. Coordinates, so all of it is muted. */
287
+ declare function streamHead(theme: Theme, options?: RowOptions): string;
288
+ /** One request. */
289
+ declare function streamRow(row: RequestRow, theme: Theme, options?: RowOptions): string;
290
+ /**
291
+ * The second line a failed request gets.
292
+ *
293
+ * The only exception to one line per request. An exception with neither type
294
+ * nor file would send the reader to `show` immediately — cheaper to print it
295
+ * here, where they are already looking.
296
+ */
297
+ declare function failureLines(row: RequestRow, detail: RequestDetail | null, theme: Theme): string[];
298
+
299
+ /**
300
+ * The screens that are text rather than data.
301
+ *
302
+ * Both of them — nothing recorded yet, and nothing answering — have to end in
303
+ * something to do. A state that only states itself leaves the reader to guess
304
+ * whether they are looking at a bug or at an empty afternoon.
305
+ */
306
+
307
+ /** The line every command prints first. */
308
+ declare function header(version: string, url: string, meta: PanelMeta, theme: Theme): string[];
309
+ /**
310
+ * The collector answered, and has nothing to show.
311
+ *
312
+ * Not an error, so nothing here is red: the header is the one a working
313
+ * stream prints, and the only coloured thing on screen is a command that can
314
+ * be copied into the next tab.
315
+ */
316
+ declare function emptyState(url: string, meta: PanelMeta, theme: Theme): string[];
317
+ /**
318
+ * A failure, as a person reads it.
319
+ *
320
+ * One bright line, then what to check. The technical cause is a `--verbose`
321
+ * away: it belongs in a bug report, and putting it above the hypotheses
322
+ * would bury them.
323
+ */
324
+ declare function renderFailure(error: unknown, theme: Theme, verbose: boolean): string[];
325
+
326
+ /**
327
+ * Fitting a line into the terminal.
328
+ *
329
+ * One column is flexible — the path — and everything else keeps its place, so
330
+ * output at 80 columns and at 200 reads the same way. When the flexible column
331
+ * hits its floor, whole columns are dropped in a fixed order rather than the
332
+ * grid collapsing.
333
+ *
334
+ * The numbers are in DESIGN.md and the table there is what these functions
335
+ * produce; the tests check both ends of it.
336
+ */
337
+ /** Below this the grid cannot be drawn at all. */
338
+ declare const MIN_WIDTH = 56;
339
+ /** Which columns a stream line has room for. */
340
+ interface StreamColumns {
341
+ readonly path: number;
342
+ readonly queries: boolean;
343
+ readonly status: boolean;
344
+ /** Printed only when asked for: it is a handle, not information. */
345
+ readonly ids: boolean;
346
+ }
347
+ /**
348
+ * How a stream line is laid out at this width.
349
+ *
350
+ * The queries column goes first — it is a number that repeats what the
351
+ * duration already implies — and the status second, because it is only
352
+ * interesting when it is not 200, and a non-2xx keeps its code in the flag
353
+ * column instead.
354
+ */
355
+ declare function streamColumns(width: number, ids?: boolean): StreamColumns;
356
+ /**
357
+ * A path and its query string, fitted into a column.
358
+ *
359
+ * Whole segments go, never characters: a truncated path stays a path and can
360
+ * still be recognised, where `/api/v2/organizat…` tells the reader nothing.
361
+ * The query string is the first thing given up, then the segments in the
362
+ * middle — the first says which service, the last which handler, and the
363
+ * identifiers between them are what nobody reads.
364
+ */
365
+ declare function fitPath(path: string, query: string | null, width: number, ellipsis: string): string;
366
+
367
+ export { CliError, type ClientOptions, DEFAULT_URL, EXIT_FAILED, EXIT_OK, EXIT_USAGE, type Globals, type ListQuery, MIN_WIDTH, ReqrayClient, type Runtime, type StreamFilter, type StreamHandlers, type Theme, UnreachableError, UsageError, emptyState, failureLines, fitPath, header, matches, normalizeUrl, plainTheme, renderFailure, resolveTheme, run, streamColumns, streamHead, streamRow };
package/dist/index.js ADDED
@@ -0,0 +1,49 @@
1
+ import {
2
+ CliError,
3
+ DEFAULT_URL,
4
+ EXIT_FAILED,
5
+ EXIT_OK,
6
+ EXIT_USAGE,
7
+ MIN_WIDTH,
8
+ ReqrayClient,
9
+ UnreachableError,
10
+ UsageError,
11
+ emptyState,
12
+ failureLines,
13
+ fitPath,
14
+ header,
15
+ matches,
16
+ normalizeUrl,
17
+ plainTheme,
18
+ renderFailure,
19
+ resolveTheme,
20
+ run,
21
+ streamColumns,
22
+ streamHead,
23
+ streamRow
24
+ } from "./chunk-V6ZCA7CU.js";
25
+ export {
26
+ CliError,
27
+ DEFAULT_URL,
28
+ EXIT_FAILED,
29
+ EXIT_OK,
30
+ EXIT_USAGE,
31
+ MIN_WIDTH,
32
+ ReqrayClient,
33
+ UnreachableError,
34
+ UsageError,
35
+ emptyState,
36
+ failureLines,
37
+ fitPath,
38
+ header,
39
+ matches,
40
+ normalizeUrl,
41
+ plainTheme,
42
+ renderFailure,
43
+ resolveTheme,
44
+ run,
45
+ streamColumns,
46
+ streamHead,
47
+ streamRow
48
+ };
49
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
package/package.json CHANGED
@@ -1,6 +1,62 @@
1
1
  {
2
2
  "name": "@reqray/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Reqray from the terminal: a live request stream and a full breakdown of one request.",
5
+ "license": "MIT",
6
+ "keywords": [
7
+ "nodejs",
8
+ "debugging",
9
+ "profiling",
10
+ "n+1",
11
+ "sql",
12
+ "observability",
13
+ "devtools",
14
+ "fastify",
15
+ "express",
16
+ "nestjs"
17
+ ],
18
+ "homepage": "https://github.com/reqray/reqray#readme",
19
+ "bugs": "https://github.com/reqray/reqray/issues",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/reqray/reqray.git",
23
+ "directory": "packages/cli"
24
+ },
25
+ "type": "module",
26
+ "engines": {
27
+ "node": ">=20"
28
+ },
29
+ "bin": {
30
+ "reqray": "./dist/cli.js"
31
+ },
32
+ "exports": {
33
+ ".": {
34
+ "import": {
35
+ "types": "./dist/index.d.ts",
36
+ "default": "./dist/index.js"
37
+ }
38
+ }
39
+ },
40
+ "module": "./dist/index.js",
41
+ "types": "./dist/index.d.ts",
42
+ "files": [
43
+ "dist",
44
+ "DESIGN.md"
45
+ ],
46
+ "publishConfig": {
47
+ "access": "public"
48
+ },
49
+ "dependencies": {
50
+ "@reqray/waterfall": "^0.1.0",
51
+ "@reqray/protocol": "^0.1.0"
52
+ },
53
+ "devDependencies": {
54
+ "@types/node": "^26.2.0",
55
+ "tsup": "^8.5.1",
56
+ "typescript": "^6.0.3"
57
+ },
58
+ "scripts": {
59
+ "build": "tsup",
60
+ "typecheck": "tsc --noEmit"
61
+ }
6
62
  }