@amritk/nish-aarch64-darwin 0.35.0 → 0.36.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.
Files changed (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
package/std/cli.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * `std/cli` — a command-line tool's help menu: whether a stream gets colour,
2
+ * `nish/cli` — a command-line tool's help menu: whether a stream gets colour,
3
3
  * the escapes that paint it, and the rows a `--help` is made of.
4
4
  *
5
5
  * import { HelpMenu, agentDriven, styleFor } from "nish/cli";
@@ -64,43 +64,81 @@ const PALETTE_MONO: i32 = 2
64
64
  * spelling the numbers. The first sixteen are the colours a theme redefines:
65
65
  * the eight basic ones and their bright twins.
66
66
  */
67
+ /** The SGR parameter for the theme's black as the text colour. */
67
68
  export const SGR_BLACK: string = "30"
69
+ /** The SGR parameter for the theme's red as the text colour. */
68
70
  export const SGR_RED: string = "31"
71
+ /** The SGR parameter for the theme's green as the text colour. */
69
72
  export const SGR_GREEN: string = "32"
73
+ /** The SGR parameter for the theme's yellow as the text colour. */
70
74
  export const SGR_YELLOW: string = "33"
75
+ /** The SGR parameter for the theme's blue as the text colour. */
71
76
  export const SGR_BLUE: string = "34"
77
+ /** The SGR parameter for the theme's magenta as the text colour. */
72
78
  export const SGR_MAGENTA: string = "35"
79
+ /** The SGR parameter for the theme's cyan as the text colour. */
73
80
  export const SGR_CYAN: string = "36"
81
+ /** The SGR parameter for the theme's white as the text colour. */
74
82
  export const SGR_WHITE: string = "37"
83
+ /** The SGR parameter for the theme's bright black (gray) as the text colour. */
75
84
  export const SGR_BRIGHT_BLACK: string = "90"
85
+ /** The SGR parameter for the theme's bright red as the text colour. */
76
86
  export const SGR_BRIGHT_RED: string = "91"
87
+ /** The SGR parameter for the theme's bright green as the text colour. */
77
88
  export const SGR_BRIGHT_GREEN: string = "92"
89
+ /** The SGR parameter for the theme's bright yellow as the text colour. */
78
90
  export const SGR_BRIGHT_YELLOW: string = "93"
91
+ /** The SGR parameter for the theme's bright blue as the text colour. */
79
92
  export const SGR_BRIGHT_BLUE: string = "94"
93
+ /** The SGR parameter for the theme's bright magenta as the text colour. */
80
94
  export const SGR_BRIGHT_MAGENTA: string = "95"
95
+ /** The SGR parameter for the theme's bright cyan as the text colour. */
81
96
  export const SGR_BRIGHT_CYAN: string = "96"
97
+ /** The SGR parameter for the theme's bright white as the text colour. */
82
98
  export const SGR_BRIGHT_WHITE: string = "97"
99
+ /** The SGR parameter for the theme's black as the background. */
83
100
  export const SGR_BG_BLACK: string = "40"
101
+ /** The SGR parameter for the theme's red as the background. */
84
102
  export const SGR_BG_RED: string = "41"
103
+ /** The SGR parameter for the theme's green as the background. */
85
104
  export const SGR_BG_GREEN: string = "42"
105
+ /** The SGR parameter for the theme's yellow as the background. */
86
106
  export const SGR_BG_YELLOW: string = "43"
107
+ /** The SGR parameter for the theme's blue as the background. */
87
108
  export const SGR_BG_BLUE: string = "44"
109
+ /** The SGR parameter for the theme's magenta as the background. */
88
110
  export const SGR_BG_MAGENTA: string = "45"
111
+ /** The SGR parameter for the theme's cyan as the background. */
89
112
  export const SGR_BG_CYAN: string = "46"
113
+ /** The SGR parameter for the theme's white as the background. */
90
114
  export const SGR_BG_WHITE: string = "47"
115
+ /** The SGR parameter for the theme's bright black as the background. */
91
116
  export const SGR_BG_BRIGHT_BLACK: string = "100"
117
+ /** The SGR parameter for the theme's bright red as the background. */
92
118
  export const SGR_BG_BRIGHT_RED: string = "101"
119
+ /** The SGR parameter for the theme's bright green as the background. */
93
120
  export const SGR_BG_BRIGHT_GREEN: string = "102"
121
+ /** The SGR parameter for the theme's bright yellow as the background. */
94
122
  export const SGR_BG_BRIGHT_YELLOW: string = "103"
123
+ /** The SGR parameter for the theme's bright blue as the background. */
95
124
  export const SGR_BG_BRIGHT_BLUE: string = "104"
125
+ /** The SGR parameter for the theme's bright magenta as the background. */
96
126
  export const SGR_BG_BRIGHT_MAGENTA: string = "105"
127
+ /** The SGR parameter for the theme's bright cyan as the background. */
97
128
  export const SGR_BG_BRIGHT_CYAN: string = "106"
129
+ /** The SGR parameter for the theme's bright white as the background. */
98
130
  export const SGR_BG_BRIGHT_WHITE: string = "107"
131
+ /** The SGR parameter for bold, or increased intensity. */
99
132
  export const SGR_BOLD: string = "1"
133
+ /** The SGR parameter for faint, or decreased intensity. */
100
134
  export const SGR_FAINT: string = "2"
135
+ /** The SGR parameter for italic, which some terminals do not show. */
101
136
  export const SGR_ITALIC: string = "3"
137
+ /** The SGR parameter for underline. */
102
138
  export const SGR_UNDERLINE: string = "4"
139
+ /** The SGR parameter for inverse: foreground and background swapped. */
103
140
  export const SGR_INVERSE: string = "7"
141
+ /** The SGR parameter for struck through. */
104
142
  export const SGR_STRIKETHROUGH: string = "9"
105
143
 
106
144
  /**
@@ -115,19 +153,70 @@ export const SGR_STRIKETHROUGH: string = "9"
115
153
  * plain.
116
154
  */
117
155
  export class Style {
118
- on: boolean
119
- colour: boolean
156
+ private on: boolean
157
+ private colour: boolean
158
+ /**
159
+ * The SGR list `heading` paints a section heading with when the terminal
160
+ * has colours: bold magenta (`"1;35"`) unless the program sets another.
161
+ */
120
162
  headingThemed: string
163
+ /**
164
+ * The SGR list `heading` paints a section heading with on the failsafe,
165
+ * where the terminal has no colours: bold (`SGR_BOLD`) unless set.
166
+ */
121
167
  headingMono: string
168
+ /**
169
+ * The SGR list `name` paints the tool's own name with when the terminal has
170
+ * colours: bold magenta (`"1;35"`) unless the program sets another.
171
+ */
122
172
  nameThemed: string
173
+ /**
174
+ * The SGR list `name` paints the tool's own name with on the failsafe,
175
+ * where the terminal has no colours: bold (`SGR_BOLD`) unless set.
176
+ */
123
177
  nameMono: string
178
+ /**
179
+ * The SGR list `flag` paints a flag or command with when the terminal has
180
+ * colours: cyan (`SGR_CYAN`) unless the program sets another.
181
+ */
124
182
  flagThemed: string
183
+ /**
184
+ * The SGR list `flag` paints a flag or command with on the failsafe, where
185
+ * the terminal has no colours: bold (`SGR_BOLD`) unless set.
186
+ */
125
187
  flagMono: string
188
+ /**
189
+ * The SGR list `meta` paints a placeholder with when the terminal has
190
+ * colours: yellow (`SGR_YELLOW`) unless the program sets another.
191
+ */
126
192
  metaThemed: string
193
+ /**
194
+ * The SGR list `meta` paints a placeholder with on the failsafe, where the
195
+ * terminal has no colours: underline (`SGR_UNDERLINE`) unless set.
196
+ */
127
197
  metaMono: string
198
+ /**
199
+ * The SGR list `dim` paints descriptions and notes with when the terminal
200
+ * has colours: faint (`SGR_FAINT`) unless the program sets another.
201
+ */
128
202
  dimThemed: string
203
+ /**
204
+ * The SGR list `dim` paints descriptions and notes with on the failsafe,
205
+ * where the terminal has no colours: empty, so plain, unless set.
206
+ */
129
207
  dimMono: string
130
208
 
209
+ /**
210
+ * A style with every role at its default pair. `styleFor` builds the right
211
+ * one for a stream; a program calls this to decide for itself.
212
+ *
213
+ * @param on whether to mark the text up at all; `false` makes every painter
214
+ * give its text back unchanged, whatever `colour` says.
215
+ * @param colour whether the terminal has colours: `true` paints the roles'
216
+ * `…Themed` lists and lets the colour painters and `sgr` paint; `false`
217
+ * is the failsafe, which paints the `…Mono` lists and the attributes and
218
+ * leaves the colour painters and `sgr` plain.
219
+ */
131
220
  constructor(on: boolean, colour: boolean) {
132
221
  this.on = on
133
222
  this.colour = colour
@@ -152,7 +241,7 @@ export class Style {
152
241
  * `text` unchanged when marking up is off or the chosen list is empty, so a
153
242
  * caller never has to ask.
154
243
  */
155
- paint(text: string, themed: string, mono: string): string {
244
+ private paint(text: string, themed: string, mono: string): string {
156
245
  const code = this.colour ? themed : mono
157
246
  if (!this.on || text.length === 0 || code.length === 0) {
158
247
  return text
@@ -160,7 +249,14 @@ export class Style {
160
249
  return `${CSI}${code}m${text}${CSI}0m`
161
250
  }
162
251
 
163
- /** A section heading, in `headingThemed` or `headingMono`. */
252
+ /**
253
+ * A section heading, in `headingThemed` or `headingMono`.
254
+ *
255
+ * @param text the words to paint, as they appear in the menu.
256
+ * @returns `text` wrapped in the heading role's escape and a reset, or `text`
257
+ * unchanged when marking up is off, `text` is empty, or the list this
258
+ * style uses for the role is empty.
259
+ */
164
260
  heading(text: string): string {
165
261
  return this.paint(text, this.headingThemed, this.headingMono)
166
262
  }
@@ -168,6 +264,11 @@ export class Style {
168
264
  /**
169
265
  * The tool's own name where it opens a line, in `nameThemed` or
170
266
  * `nameMono`.
267
+ *
268
+ * @param text the words to paint, as they appear in the menu.
269
+ * @returns `text` wrapped in the name role's escape and a reset, or `text`
270
+ * unchanged when marking up is off, `text` is empty, or the list this
271
+ * style uses for the role is empty.
171
272
  */
172
273
  name(text: string): string {
173
274
  return this.paint(text, this.nameThemed, this.nameMono)
@@ -176,6 +277,11 @@ export class Style {
176
277
  /**
177
278
  * A flag, or a command a person would type, in `flagThemed` or
178
279
  * `flagMono`.
280
+ *
281
+ * @param text the words to paint, as they appear in the menu.
282
+ * @returns `text` wrapped in the flag role's escape and a reset, or `text`
283
+ * unchanged when marking up is off, `text` is empty, or the list this
284
+ * style uses for the role is empty.
179
285
  */
180
286
  flag(text: string): string {
181
287
  return this.paint(text, this.flagThemed, this.flagMono)
@@ -184,6 +290,11 @@ export class Style {
184
290
  /**
185
291
  * A placeholder the person fills in, such as `<file.ts>` or `speed|size`, in
186
292
  * `metaThemed` or `metaMono`.
293
+ *
294
+ * @param text the words to paint, as they appear in the menu.
295
+ * @returns `text` wrapped in the meta role's escape and a reset, or `text`
296
+ * unchanged when marking up is off, `text` is empty, or the list this
297
+ * style uses for the role is empty.
187
298
  */
188
299
  meta(text: string): string {
189
300
  return this.paint(text, this.metaThemed, this.metaMono)
@@ -192,6 +303,11 @@ export class Style {
192
303
  /**
193
304
  * Text that explains rather than names, such as descriptions and notes, in
194
305
  * `dimThemed` or `dimMono`.
306
+ *
307
+ * @param text the words to paint, as they appear in the menu.
308
+ * @returns `text` wrapped in the dim role's escape and a reset, or `text`
309
+ * unchanged when marking up is off, `text` is empty, or the list this
310
+ * style uses for the role is empty.
195
311
  */
196
312
  dim(text: string): string {
197
313
  return this.paint(text, this.dimThemed, this.dimMono)
@@ -203,6 +319,13 @@ export class Style {
203
319
  * 256-colour and truecolor, which ignore the reader's theme, so they stay
204
320
  * the caller's explicit choice. The failsafe paints nothing, since the list
205
321
  * may name a colour a monochrome terminal cannot show.
322
+ *
323
+ * @param text the words to paint.
324
+ * @param codes the SGR parameters, separated by `;`, without the CSI before
325
+ * them or the `m` after; an empty list leaves `text` plain.
326
+ * @returns `text` wrapped in the escape for `codes` and a reset, or `text`
327
+ * unchanged when colour is off (the failsafe included), `text` is empty,
328
+ * or `codes` is.
206
329
  */
207
330
  sgr(text: string, codes: string): string {
208
331
  return this.paint(text, codes, "")
@@ -212,192 +335,422 @@ export class Style {
212
335
  // colours to show, paints none of them; the attribute painters paint under
213
336
  // both.
214
337
 
215
- /** `text` in the theme's black. */
338
+ /**
339
+ * `text` in the theme's black (`SGR_BLACK`).
340
+ *
341
+ * @param text the words to colour.
342
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
343
+ * when colour is off (the failsafe included) or `text` is empty.
344
+ */
216
345
  black(text: string): string {
217
346
  return this.sgr(text, SGR_BLACK)
218
347
  }
219
348
 
220
- /** `text` in the theme's red. */
349
+ /**
350
+ * `text` in the theme's red (`SGR_RED`).
351
+ *
352
+ * @param text the words to colour.
353
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
354
+ * when colour is off (the failsafe included) or `text` is empty.
355
+ */
221
356
  red(text: string): string {
222
357
  return this.sgr(text, SGR_RED)
223
358
  }
224
359
 
225
- /** `text` in the theme's green. */
360
+ /**
361
+ * `text` in the theme's green (`SGR_GREEN`).
362
+ *
363
+ * @param text the words to colour.
364
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
365
+ * when colour is off (the failsafe included) or `text` is empty.
366
+ */
226
367
  green(text: string): string {
227
368
  return this.sgr(text, SGR_GREEN)
228
369
  }
229
370
 
230
- /** `text` in the theme's yellow. */
371
+ /**
372
+ * `text` in the theme's yellow (`SGR_YELLOW`).
373
+ *
374
+ * @param text the words to colour.
375
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
376
+ * when colour is off (the failsafe included) or `text` is empty.
377
+ */
231
378
  yellow(text: string): string {
232
379
  return this.sgr(text, SGR_YELLOW)
233
380
  }
234
381
 
235
- /** `text` in the theme's blue. */
382
+ /**
383
+ * `text` in the theme's blue (`SGR_BLUE`).
384
+ *
385
+ * @param text the words to colour.
386
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
387
+ * when colour is off (the failsafe included) or `text` is empty.
388
+ */
236
389
  blue(text: string): string {
237
390
  return this.sgr(text, SGR_BLUE)
238
391
  }
239
392
 
240
- /** `text` in the theme's magenta. */
393
+ /**
394
+ * `text` in the theme's magenta (`SGR_MAGENTA`).
395
+ *
396
+ * @param text the words to colour.
397
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
398
+ * when colour is off (the failsafe included) or `text` is empty.
399
+ */
241
400
  magenta(text: string): string {
242
401
  return this.sgr(text, SGR_MAGENTA)
243
402
  }
244
403
 
245
- /** `text` in the theme's cyan. */
404
+ /**
405
+ * `text` in the theme's cyan (`SGR_CYAN`).
406
+ *
407
+ * @param text the words to colour.
408
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
409
+ * when colour is off (the failsafe included) or `text` is empty.
410
+ */
246
411
  cyan(text: string): string {
247
412
  return this.sgr(text, SGR_CYAN)
248
413
  }
249
414
 
250
- /** `text` in the theme's white. */
415
+ /**
416
+ * `text` in the theme's white (`SGR_WHITE`).
417
+ *
418
+ * @param text the words to colour.
419
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
420
+ * when colour is off (the failsafe included) or `text` is empty.
421
+ */
251
422
  white(text: string): string {
252
423
  return this.sgr(text, SGR_WHITE)
253
424
  }
254
425
 
255
- /** `text` in the theme's bright black (gray). */
426
+ /**
427
+ * `text` in the theme's bright black, a gray (`SGR_BRIGHT_BLACK`).
428
+ *
429
+ * @param text the words to colour.
430
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
431
+ * when colour is off (the failsafe included) or `text` is empty.
432
+ */
256
433
  brightBlack(text: string): string {
257
434
  return this.sgr(text, SGR_BRIGHT_BLACK)
258
435
  }
259
436
 
260
- /** `text` in the theme's bright red. */
437
+ /**
438
+ * `text` in the theme's bright red (`SGR_BRIGHT_RED`).
439
+ *
440
+ * @param text the words to colour.
441
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
442
+ * when colour is off (the failsafe included) or `text` is empty.
443
+ */
261
444
  brightRed(text: string): string {
262
445
  return this.sgr(text, SGR_BRIGHT_RED)
263
446
  }
264
447
 
265
- /** `text` in the theme's bright green. */
448
+ /**
449
+ * `text` in the theme's bright green (`SGR_BRIGHT_GREEN`).
450
+ *
451
+ * @param text the words to colour.
452
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
453
+ * when colour is off (the failsafe included) or `text` is empty.
454
+ */
266
455
  brightGreen(text: string): string {
267
456
  return this.sgr(text, SGR_BRIGHT_GREEN)
268
457
  }
269
458
 
270
- /** `text` in the theme's bright yellow. */
459
+ /**
460
+ * `text` in the theme's bright yellow (`SGR_BRIGHT_YELLOW`).
461
+ *
462
+ * @param text the words to colour.
463
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
464
+ * when colour is off (the failsafe included) or `text` is empty.
465
+ */
271
466
  brightYellow(text: string): string {
272
467
  return this.sgr(text, SGR_BRIGHT_YELLOW)
273
468
  }
274
469
 
275
- /** `text` in the theme's bright blue. */
470
+ /**
471
+ * `text` in the theme's bright blue (`SGR_BRIGHT_BLUE`).
472
+ *
473
+ * @param text the words to colour.
474
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
475
+ * when colour is off (the failsafe included) or `text` is empty.
476
+ */
276
477
  brightBlue(text: string): string {
277
478
  return this.sgr(text, SGR_BRIGHT_BLUE)
278
479
  }
279
480
 
280
- /** `text` in the theme's bright magenta. */
481
+ /**
482
+ * `text` in the theme's bright magenta (`SGR_BRIGHT_MAGENTA`).
483
+ *
484
+ * @param text the words to colour.
485
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
486
+ * when colour is off (the failsafe included) or `text` is empty.
487
+ */
281
488
  brightMagenta(text: string): string {
282
489
  return this.sgr(text, SGR_BRIGHT_MAGENTA)
283
490
  }
284
491
 
285
- /** `text` in the theme's bright cyan. */
492
+ /**
493
+ * `text` in the theme's bright cyan (`SGR_BRIGHT_CYAN`).
494
+ *
495
+ * @param text the words to colour.
496
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
497
+ * when colour is off (the failsafe included) or `text` is empty.
498
+ */
286
499
  brightCyan(text: string): string {
287
500
  return this.sgr(text, SGR_BRIGHT_CYAN)
288
501
  }
289
502
 
290
- /** `text` in the theme's bright white. */
503
+ /**
504
+ * `text` in the theme's bright white (`SGR_BRIGHT_WHITE`).
505
+ *
506
+ * @param text the words to colour.
507
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
508
+ * when colour is off (the failsafe included) or `text` is empty.
509
+ */
291
510
  brightWhite(text: string): string {
292
511
  return this.sgr(text, SGR_BRIGHT_WHITE)
293
512
  }
294
513
 
295
- /** `text` on the theme's black. */
514
+ /**
515
+ * `text` on the theme's black (`SGR_BG_BLACK`).
516
+ *
517
+ * @param text the words to colour.
518
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
519
+ * when colour is off (the failsafe included) or `text` is empty.
520
+ */
296
521
  bgBlack(text: string): string {
297
522
  return this.sgr(text, SGR_BG_BLACK)
298
523
  }
299
524
 
300
- /** `text` on the theme's red. */
525
+ /**
526
+ * `text` on the theme's red (`SGR_BG_RED`).
527
+ *
528
+ * @param text the words to colour.
529
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
530
+ * when colour is off (the failsafe included) or `text` is empty.
531
+ */
301
532
  bgRed(text: string): string {
302
533
  return this.sgr(text, SGR_BG_RED)
303
534
  }
304
535
 
305
- /** `text` on the theme's green. */
536
+ /**
537
+ * `text` on the theme's green (`SGR_BG_GREEN`).
538
+ *
539
+ * @param text the words to colour.
540
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
541
+ * when colour is off (the failsafe included) or `text` is empty.
542
+ */
306
543
  bgGreen(text: string): string {
307
544
  return this.sgr(text, SGR_BG_GREEN)
308
545
  }
309
546
 
310
- /** `text` on the theme's yellow. */
547
+ /**
548
+ * `text` on the theme's yellow (`SGR_BG_YELLOW`).
549
+ *
550
+ * @param text the words to colour.
551
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
552
+ * when colour is off (the failsafe included) or `text` is empty.
553
+ */
311
554
  bgYellow(text: string): string {
312
555
  return this.sgr(text, SGR_BG_YELLOW)
313
556
  }
314
557
 
315
- /** `text` on the theme's blue. */
558
+ /**
559
+ * `text` on the theme's blue (`SGR_BG_BLUE`).
560
+ *
561
+ * @param text the words to colour.
562
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
563
+ * when colour is off (the failsafe included) or `text` is empty.
564
+ */
316
565
  bgBlue(text: string): string {
317
566
  return this.sgr(text, SGR_BG_BLUE)
318
567
  }
319
568
 
320
- /** `text` on the theme's magenta. */
569
+ /**
570
+ * `text` on the theme's magenta (`SGR_BG_MAGENTA`).
571
+ *
572
+ * @param text the words to colour.
573
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
574
+ * when colour is off (the failsafe included) or `text` is empty.
575
+ */
321
576
  bgMagenta(text: string): string {
322
577
  return this.sgr(text, SGR_BG_MAGENTA)
323
578
  }
324
579
 
325
- /** `text` on the theme's cyan. */
580
+ /**
581
+ * `text` on the theme's cyan (`SGR_BG_CYAN`).
582
+ *
583
+ * @param text the words to colour.
584
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
585
+ * when colour is off (the failsafe included) or `text` is empty.
586
+ */
326
587
  bgCyan(text: string): string {
327
588
  return this.sgr(text, SGR_BG_CYAN)
328
589
  }
329
590
 
330
- /** `text` on the theme's white. */
591
+ /**
592
+ * `text` on the theme's white (`SGR_BG_WHITE`).
593
+ *
594
+ * @param text the words to colour.
595
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
596
+ * when colour is off (the failsafe included) or `text` is empty.
597
+ */
331
598
  bgWhite(text: string): string {
332
599
  return this.sgr(text, SGR_BG_WHITE)
333
600
  }
334
601
 
335
- /** `text` on the theme's bright black. */
602
+ /**
603
+ * `text` on the theme's bright black (`SGR_BG_BRIGHT_BLACK`).
604
+ *
605
+ * @param text the words to colour.
606
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
607
+ * when colour is off (the failsafe included) or `text` is empty.
608
+ */
336
609
  bgBrightBlack(text: string): string {
337
610
  return this.sgr(text, SGR_BG_BRIGHT_BLACK)
338
611
  }
339
612
 
340
- /** `text` on the theme's bright red. */
613
+ /**
614
+ * `text` on the theme's bright red (`SGR_BG_BRIGHT_RED`).
615
+ *
616
+ * @param text the words to colour.
617
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
618
+ * when colour is off (the failsafe included) or `text` is empty.
619
+ */
341
620
  bgBrightRed(text: string): string {
342
621
  return this.sgr(text, SGR_BG_BRIGHT_RED)
343
622
  }
344
623
 
345
- /** `text` on the theme's bright green. */
624
+ /**
625
+ * `text` on the theme's bright green (`SGR_BG_BRIGHT_GREEN`).
626
+ *
627
+ * @param text the words to colour.
628
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
629
+ * when colour is off (the failsafe included) or `text` is empty.
630
+ */
346
631
  bgBrightGreen(text: string): string {
347
632
  return this.sgr(text, SGR_BG_BRIGHT_GREEN)
348
633
  }
349
634
 
350
- /** `text` on the theme's bright yellow. */
635
+ /**
636
+ * `text` on the theme's bright yellow (`SGR_BG_BRIGHT_YELLOW`).
637
+ *
638
+ * @param text the words to colour.
639
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
640
+ * when colour is off (the failsafe included) or `text` is empty.
641
+ */
351
642
  bgBrightYellow(text: string): string {
352
643
  return this.sgr(text, SGR_BG_BRIGHT_YELLOW)
353
644
  }
354
645
 
355
- /** `text` on the theme's bright blue. */
646
+ /**
647
+ * `text` on the theme's bright blue (`SGR_BG_BRIGHT_BLUE`).
648
+ *
649
+ * @param text the words to colour.
650
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
651
+ * when colour is off (the failsafe included) or `text` is empty.
652
+ */
356
653
  bgBrightBlue(text: string): string {
357
654
  return this.sgr(text, SGR_BG_BRIGHT_BLUE)
358
655
  }
359
656
 
360
- /** `text` on the theme's bright magenta. */
657
+ /**
658
+ * `text` on the theme's bright magenta (`SGR_BG_BRIGHT_MAGENTA`).
659
+ *
660
+ * @param text the words to colour.
661
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
662
+ * when colour is off (the failsafe included) or `text` is empty.
663
+ */
361
664
  bgBrightMagenta(text: string): string {
362
665
  return this.sgr(text, SGR_BG_BRIGHT_MAGENTA)
363
666
  }
364
667
 
365
- /** `text` on the theme's bright cyan. */
668
+ /**
669
+ * `text` on the theme's bright cyan (`SGR_BG_BRIGHT_CYAN`).
670
+ *
671
+ * @param text the words to colour.
672
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
673
+ * when colour is off (the failsafe included) or `text` is empty.
674
+ */
366
675
  bgBrightCyan(text: string): string {
367
676
  return this.sgr(text, SGR_BG_BRIGHT_CYAN)
368
677
  }
369
678
 
370
- /** `text` on the theme's bright white. */
679
+ /**
680
+ * `text` on the theme's bright white (`SGR_BG_BRIGHT_WHITE`).
681
+ *
682
+ * @param text the words to colour.
683
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
684
+ * when colour is off (the failsafe included) or `text` is empty.
685
+ */
371
686
  bgBrightWhite(text: string): string {
372
687
  return this.sgr(text, SGR_BG_BRIGHT_WHITE)
373
688
  }
374
689
 
375
- /** `text` bold. */
690
+ /**
691
+ * `text` bold (`SGR_BOLD`), under the failsafe too.
692
+ *
693
+ * @param text the words to mark up.
694
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
695
+ * when marking up is off or `text` is empty.
696
+ */
376
697
  bold(text: string): string {
377
698
  return this.paint(text, SGR_BOLD, SGR_BOLD)
378
699
  }
379
700
 
380
- /** `text` faint. */
701
+ /**
702
+ * `text` faint (`SGR_FAINT`), under the failsafe too.
703
+ *
704
+ * @param text the words to mark up.
705
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
706
+ * when marking up is off or `text` is empty.
707
+ */
381
708
  faint(text: string): string {
382
709
  return this.paint(text, SGR_FAINT, SGR_FAINT)
383
710
  }
384
711
 
385
- /** `text` italic, where the terminal has it. */
712
+ /**
713
+ * `text` italic (`SGR_ITALIC`), where the terminal has it, under the
714
+ * failsafe too.
715
+ *
716
+ * @param text the words to mark up.
717
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
718
+ * when marking up is off or `text` is empty.
719
+ */
386
720
  italic(text: string): string {
387
721
  return this.paint(text, SGR_ITALIC, SGR_ITALIC)
388
722
  }
389
723
 
390
- /** `text` underlined. */
724
+ /**
725
+ * `text` underlined (`SGR_UNDERLINE`), under the failsafe too.
726
+ *
727
+ * @param text the words to mark up.
728
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
729
+ * when marking up is off or `text` is empty.
730
+ */
391
731
  underline(text: string): string {
392
732
  return this.paint(text, SGR_UNDERLINE, SGR_UNDERLINE)
393
733
  }
394
734
 
395
- /** `text` with foreground and background swapped. */
735
+ /**
736
+ * `text` with foreground and background swapped (`SGR_INVERSE`), under
737
+ * the failsafe too.
738
+ *
739
+ * @param text the words to mark up.
740
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
741
+ * when marking up is off or `text` is empty.
742
+ */
396
743
  inverse(text: string): string {
397
744
  return this.paint(text, SGR_INVERSE, SGR_INVERSE)
398
745
  }
399
746
 
400
- /** `text` struck through. */
747
+ /**
748
+ * `text` struck through (`SGR_STRIKETHROUGH`), under the failsafe too.
749
+ *
750
+ * @param text the words to mark up.
751
+ * @returns `text` wrapped in the escape and a reset, or `text` unchanged
752
+ * when marking up is off or `text` is empty.
753
+ */
401
754
  strikethrough(text: string): string {
402
755
  return this.paint(text, SGR_STRIKETHROUGH, SGR_STRIKETHROUGH)
403
756
  }
@@ -478,6 +831,9 @@ const styleOfPalette = (palette: i32): Style => {
478
831
  * value for yes. Without it, the variables the agents that set one put in
479
832
  * their commands' environment (Claude Code's `CLAUDECODE`, Gemini CLI's
480
833
  * `GEMINI_CLI`) say yes.
834
+ *
835
+ * @returns `true` when an agent is judged to be at the keyboard, the answer
836
+ * `styleFor`'s `agent` takes; it reads the environment afresh each call.
481
837
  */
482
838
  export const agentDriven = (): boolean => {
483
839
  if (envIsSet("NISH_AGENT")) {
@@ -496,6 +852,14 @@ export const agentDriven = (): boolean => {
496
852
  * colour is the theme's, asked of nothing: the reader is a pager or an editor
497
853
  * that renders the escapes itself (Emacs's shell sets `TERM=dumb` and paints
498
854
  * ANSI colour), so `TERM` does not describe it, and forcing forks nothing.
855
+ *
856
+ * @param fd the descriptor the painted text is written to, 1 for standard
857
+ * output or 2 for standard error; only the terminal check reads it.
858
+ * @param agent whether the reader is an agent, as `agentDriven` answered;
859
+ * `true` gives plain text, whatever forces colour.
860
+ * @returns a new `Style` each call, the caller's to keep and recolour: one
861
+ * that paints the theme, one that paints the failsafe, or one that paints
862
+ * nothing.
499
863
  */
500
864
  export const styleFor = (fd: i32, agent: boolean): Style => {
501
865
  const level = getenv("FORCE_COLOR")
@@ -544,13 +908,27 @@ const padTo = (width: i32, column: i32): string => spaces(width + 2 <= column ?
544
908
  * up whether or not `style` paints, as long as the text is ASCII.
545
909
  */
546
910
  export class HelpMenu {
547
- style: Style
548
- program: string
549
- column: i32
550
- usageColumn: i32
551
- lines: string[]
552
- usages: i32
911
+ private style: Style
912
+ private program: string
913
+ private column: i32
914
+ private usageColumn: i32
915
+ private lines: string[]
916
+ private usages: i32
553
917
 
918
+ /**
919
+ * An empty menu; nothing is written until `text` is asked for.
920
+ *
921
+ * @param style the painter for every line the menu builds. The menu keeps
922
+ * this same `Style`, not a copy, so a role recoloured on it later paints
923
+ * the lines added after.
924
+ * @param program the tool's name, which opens the title line and every
925
+ * usage line.
926
+ * @param column how many plain columns come before a row's description,
927
+ * counted from the start of the line; a row whose flag and placeholder
928
+ * reach within two columns of it gets two spaces instead.
929
+ * @param usageColumn the same for a usage line's description, counted from
930
+ * the start of `usage:`; set it past the longest command shape.
931
+ */
554
932
  constructor(style: Style, program: string, column: i32, usageColumn: i32) {
555
933
  this.style = style
556
934
  this.program = program
@@ -560,7 +938,14 @@ export class HelpMenu {
560
938
  this.usages = 0
561
939
  }
562
940
 
563
- /** The opening line, the program's name, `version` and a one-line `summary`, and a blank after it. */
941
+ /**
942
+ * The opening line, the program's name, `version` and a one-line `summary`,
943
+ * and a blank after it.
944
+ *
945
+ * @param version the version shown after the name, faint, such as `1.0.0`.
946
+ * @param summary what the tool is for, in a few words, faint, two spaces
947
+ * after the version.
948
+ */
564
949
  header(version: string, summary: string): void {
565
950
  this.title(version, summary)
566
951
  this.lines.push("")
@@ -569,6 +954,9 @@ export class HelpMenu {
569
954
  /**
570
955
  * The opening line alone, without `header`'s blank after it, for a menu that
571
956
  * puts something under its title (`line`) before the blank.
957
+ *
958
+ * @param version the version shown after the name, faint.
959
+ * @param summary what the tool is for, faint, two spaces after the version.
572
960
  */
573
961
  title(version: string, summary: string): void {
574
962
  const style = this.style
@@ -578,6 +966,9 @@ export class HelpMenu {
578
966
  /**
579
967
  * A line exactly as given, painted (or not) by the caller with the menu's
580
968
  * `style`: a rule, a banner, a blank. Its width is the caller's to keep.
969
+ *
970
+ * @param text the whole line, with any escapes already in it; `""` adds a
971
+ * blank line.
581
972
  */
582
973
  line(text: string): void {
583
974
  this.lines.push(text)
@@ -587,6 +978,11 @@ export class HelpMenu {
587
978
  * A usage line: the command `shape` after the program's name, and what it
588
979
  * is for (`description` may be empty). The first opens with `usage:` and
589
980
  * the rest are indented under it.
981
+ *
982
+ * @param shape the arguments and flags that follow the program's name, such
983
+ * as `<file.ts> [flags]`, painted as a flag.
984
+ * @param description what this form of the command does, faint, starting at
985
+ * `usageColumn`; `""` ends the line after `shape`.
590
986
  */
591
987
  usage(shape: string, description: string): void {
592
988
  const style = this.style
@@ -597,7 +993,11 @@ export class HelpMenu {
597
993
  this.usages = this.usages + 1
598
994
  }
599
995
 
600
- /** A section: a blank line, then `title` as a heading. */
996
+ /**
997
+ * A section: a blank line, then `title` as a heading.
998
+ *
999
+ * @param title the section's name, such as `Flags`, as it is shown.
1000
+ */
601
1001
  section(title: string): void {
602
1002
  this.lines.push("")
603
1003
  this.lines.push(this.style.heading(title))
@@ -606,6 +1006,12 @@ export class HelpMenu {
606
1006
  /**
607
1007
  * One row: the `flag` (or a command), its placeholder `meta` (may be
608
1008
  * empty), and what it does, the description starting at `column`.
1009
+ *
1010
+ * @param flag the flag or command a person types, painted as a flag after
1011
+ * a two-space indent.
1012
+ * @param meta the placeholder for the flag's value, such as `<n>`, after
1013
+ * one space; `""` for a flag that takes none.
1014
+ * @param description what the flag does, faint.
609
1015
  */
610
1016
  row(flag: string, meta: string, description: string): void {
611
1017
  const style = this.style
@@ -616,17 +1022,32 @@ export class HelpMenu {
616
1022
  )
617
1023
  }
618
1024
 
619
- /** An indented line of prose, faint. */
1025
+ /**
1026
+ * An indented line of prose, faint.
1027
+ *
1028
+ * @param text the prose, shown after two spaces.
1029
+ */
620
1030
  note(text: string): void {
621
1031
  this.lines.push(` ${this.style.dim(text)}`)
622
1032
  }
623
1033
 
624
- /** An indented line the reader fills in or opens, a path or a value, as a placeholder. */
1034
+ /**
1035
+ * An indented line the reader fills in or opens, a path or a value, as a
1036
+ * placeholder.
1037
+ *
1038
+ * @param text the path or value, shown after two spaces.
1039
+ */
625
1040
  value(text: string): void {
626
1041
  this.lines.push(` ${this.style.meta(text)}`)
627
1042
  }
628
1043
 
629
- /** The menu so far, its lines joined by newlines, with no newline after the last. */
1044
+ /**
1045
+ * The menu so far, its lines joined by newlines, with no newline after the
1046
+ * last.
1047
+ *
1048
+ * @returns a new string each call; the menu keeps its lines, so a later
1049
+ * call also has what was added since.
1050
+ */
630
1051
  text(): string {
631
1052
  return this.lines.join("\n")
632
1053
  }