@intellectual-frontiers/ergonex 0.2.5 → 0.3.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 (93) hide show
  1. package/README.md +2 -0
  2. package/dist/desired.d.ts +27 -0
  3. package/dist/diff.d.ts +12 -0
  4. package/dist/doctor.d.ts +79 -0
  5. package/dist/findings.d.ts +85 -0
  6. package/dist/layout.d.ts +83 -0
  7. package/dist/manifest.d.ts +84 -0
  8. package/dist/mod.d.ts +29 -0
  9. package/dist/mod.js +4219 -0
  10. package/dist/modules/external.d.ts +31 -0
  11. package/dist/modules/mod.d.ts +10 -0
  12. package/dist/modules/name.d.ts +32 -0
  13. package/dist/modules/registry.d.ts +51 -0
  14. package/dist/modules/types.d.ts +178 -0
  15. package/dist/places.d.ts +35 -0
  16. package/dist/plan.d.ts +176 -0
  17. package/dist/platform/k-args.d.ts +28 -0
  18. package/dist/policy.d.ts +39 -0
  19. package/dist/portable.d.ts +111 -0
  20. package/dist/render.d.ts +95 -0
  21. package/dist/setup/evidence.d.ts +58 -0
  22. package/dist/shell/block.d.ts +45 -0
  23. package/dist/shell/mod.d.ts +8 -0
  24. package/dist/shell/snippet.d.ts +43 -0
  25. package/dist/state-record.d.ts +59 -0
  26. package/dist/state.d.ts +64 -0
  27. package/dist/templates/data.d.ts +25 -0
  28. package/dist/templates/hooks.d.ts +13 -0
  29. package/dist/templates/mod.d.ts +16 -0
  30. package/dist/tools/catalog.d.ts +70 -0
  31. package/dist/types.d.ts +51 -0
  32. package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
  33. package/dist/vendor/ts/githost/git.d.ts +16 -0
  34. package/dist/vendor/ts/githost/github.d.ts +15 -0
  35. package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
  36. package/dist/vendor/ts/githost/mod.d.ts +29 -0
  37. package/dist/vendor/ts/githost/remote.d.ts +59 -0
  38. package/dist/vendor/ts/githost/types.d.ts +101 -0
  39. package/dist/vendor/ts/kernel/archive.d.ts +147 -0
  40. package/dist/vendor/ts/kernel/args.d.ts +240 -0
  41. package/dist/vendor/ts/kernel/assess.d.ts +247 -0
  42. package/dist/vendor/ts/kernel/attest.d.ts +164 -0
  43. package/dist/vendor/ts/kernel/base64.d.ts +24 -0
  44. package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
  45. package/dist/vendor/ts/kernel/cms.d.ts +106 -0
  46. package/dist/vendor/ts/kernel/commands.d.ts +103 -0
  47. package/dist/vendor/ts/kernel/cose.d.ts +34 -0
  48. package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
  49. package/dist/vendor/ts/kernel/csv.d.ts +38 -0
  50. package/dist/vendor/ts/kernel/der.d.ts +67 -0
  51. package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
  52. package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
  53. package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
  54. package/dist/vendor/ts/kernel/glob.d.ts +64 -0
  55. package/dist/vendor/ts/kernel/grc.d.ts +356 -0
  56. package/dist/vendor/ts/kernel/http.d.ts +46 -0
  57. package/dist/vendor/ts/kernel/json5.d.ts +46 -0
  58. package/dist/vendor/ts/kernel/layers.d.ts +35 -0
  59. package/dist/vendor/ts/kernel/md5.d.ts +19 -0
  60. package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
  61. package/dist/vendor/ts/kernel/mod.d.ts +95 -0
  62. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
  63. package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
  64. package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
  65. package/dist/vendor/ts/kernel/otel.d.ts +365 -0
  66. package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
  67. package/dist/vendor/ts/kernel/palette.d.ts +44 -0
  68. package/dist/vendor/ts/kernel/png.d.ts +124 -0
  69. package/dist/vendor/ts/kernel/rdf-schema.d.ts +190 -0
  70. package/dist/vendor/ts/kernel/rdf-term.d.ts +162 -0
  71. package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +148 -0
  72. package/dist/vendor/ts/kernel/rdf-write.d.ts +25 -0
  73. package/dist/vendor/ts/kernel/rdf.d.ts +35 -0
  74. package/dist/vendor/ts/kernel/render.d.ts +111 -0
  75. package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
  76. package/dist/vendor/ts/kernel/semver.d.ts +94 -0
  77. package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
  78. package/dist/vendor/ts/kernel/signals.d.ts +371 -0
  79. package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
  80. package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
  81. package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
  82. package/dist/vendor/ts/kernel/toml.d.ts +51 -0
  83. package/dist/vendor/ts/kernel/trace.d.ts +169 -0
  84. package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
  85. package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
  86. package/dist/vendor/ts/kernel/vt.d.ts +78 -0
  87. package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
  88. package/dist/vendor/ts/kernel/width.d.ts +63 -0
  89. package/dist/vendor/ts/kernel/xml.d.ts +73 -0
  90. package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
  91. package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
  92. package/ergonex.mjs +140 -140
  93. package/package.json +17 -5
@@ -0,0 +1,78 @@
1
+ /** A colour of text or background: the terminal's default, one of 256 indexed colours (0 to 15 the basic and bright ones), or 24-bit. */
2
+ export type Colour = {
3
+ readonly kind: "default";
4
+ } | {
5
+ readonly kind: "indexed";
6
+ readonly index: number;
7
+ } | {
8
+ readonly kind: "rgb";
9
+ readonly r: number;
10
+ readonly g: number;
11
+ readonly b: number;
12
+ };
13
+ /** How a cell's text is drawn, as SGR left it. */
14
+ export type Style = {
15
+ readonly bold: boolean;
16
+ readonly dim: boolean;
17
+ readonly italic: boolean;
18
+ readonly underline: boolean;
19
+ readonly blink: boolean;
20
+ readonly inverse: boolean;
21
+ readonly hidden: boolean;
22
+ readonly strike: boolean;
23
+ readonly fg: Colour;
24
+ readonly bg: Colour;
25
+ };
26
+ /** The style of a cell nothing styled: every attribute off, default colours. */
27
+ export declare const PLAIN: Style;
28
+ /** A style in words, for a snapshot: the attributes on, then `fg=` and `bg=` where not the default; "" for `PLAIN`. */
29
+ export declare function describeStyle(style: Style): string;
30
+ /** Whether two styles draw the same. */
31
+ export declare function sameStyle(a: Style, b: Style): boolean;
32
+ /** One cell of the screen: a grapheme and its style; a wide grapheme's second cell is a continuation, of width 0 and empty text. */
33
+ export type Cell = {
34
+ readonly text: string;
35
+ readonly width: 0 | 1 | 2;
36
+ readonly style: Style;
37
+ };
38
+ /** A run of cells of one style on a line, their text joined. */
39
+ export type Run = {
40
+ readonly text: string;
41
+ readonly style: Style;
42
+ };
43
+ /** Where the cursor is (row and column from 0) and whether it is shown. */
44
+ export type Cursor = {
45
+ readonly row: number;
46
+ readonly col: number;
47
+ readonly visible: boolean;
48
+ };
49
+ /** The size of a screen and how it reads a line feed. */
50
+ export type ScreenOptions = {
51
+ /** Columns; at least 1. */
52
+ readonly width: number;
53
+ /** Rows: the screen scrolls when a line feed is written on the last; without it, the screen grows. */
54
+ readonly height?: number;
55
+ /** "crlf" (the default): a line feed also returns the carriage, as a terminal's line discipline does; "lf": it only moves down. */
56
+ readonly newline?: "crlf" | "lf";
57
+ };
58
+ /** A screen being written to. */
59
+ export type Screen = {
60
+ /** Its width in columns. */
61
+ readonly width: number;
62
+ /** Its height in rows, or undefined where it grows. */
63
+ readonly height: number | undefined;
64
+ /** Feeds it what a program writes: text, or bytes decoded as UTF-8 (a character may be split across writes). */
65
+ write(data: string | Uint8Array): void;
66
+ /** Its lines as text: trailing spaces of each line and trailing empty lines left out. */
67
+ lines(): readonly string[];
68
+ /** Its lines joined by "\n". */
69
+ text(): string;
70
+ /** Its lines as runs of one style, trailing unstyled spaces and trailing empty lines left out. */
71
+ styled(): readonly (readonly Run[])[];
72
+ /** The cell at a row and column; undefined outside the screen. */
73
+ cell(row: number, col: number): Cell | undefined;
74
+ /** The cursor. */
75
+ cursor(): Cursor;
76
+ };
77
+ /** A new, empty screen with the cursor at the top left, shown. */
78
+ export declare function createScreen(options: ScreenOptions): Screen;
@@ -0,0 +1,212 @@
1
+ import { type CborKey, type CborValue } from "./cbor.js";
2
+ import { type Result } from "@intellectual-frontiers/core";
3
+ /** A relying party as the options name it. */
4
+ export type PublicKeyCredentialRpEntity = {
5
+ readonly id?: string;
6
+ readonly name: string;
7
+ };
8
+ /** A user account as the options name it (`id` base64url, at most 64 bytes). */
9
+ export type PublicKeyCredentialUserEntityJSON = {
10
+ readonly id: string;
11
+ readonly name: string;
12
+ readonly displayName: string;
13
+ };
14
+ /** An algorithm offered for a new credential. */
15
+ export type PublicKeyCredentialParameters = {
16
+ readonly type: "public-key";
17
+ readonly alg: number;
18
+ };
19
+ /** A credential named by its id (base64url). */
20
+ export type PublicKeyCredentialDescriptorJSON = {
21
+ readonly type: "public-key";
22
+ readonly id: string;
23
+ readonly transports?: readonly string[];
24
+ };
25
+ /** What kind of authenticator is wanted. */
26
+ export type AuthenticatorSelectionCriteria = {
27
+ readonly authenticatorAttachment?: "platform" | "cross-platform";
28
+ readonly residentKey?: "discouraged" | "preferred" | "required";
29
+ readonly requireResidentKey?: boolean;
30
+ readonly userVerification?: "required" | "preferred" | "discouraged";
31
+ };
32
+ /** The options of `navigator.credentials.create({ publicKey })` as JSON (`PublicKeyCredential.parseCreationOptionsFromJSON` takes it). */
33
+ export type PublicKeyCredentialCreationOptionsJSON = {
34
+ readonly rp: PublicKeyCredentialRpEntity;
35
+ readonly user: PublicKeyCredentialUserEntityJSON;
36
+ readonly challenge: string;
37
+ readonly pubKeyCredParams: readonly PublicKeyCredentialParameters[];
38
+ readonly timeout?: number;
39
+ readonly excludeCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
40
+ readonly authenticatorSelection?: AuthenticatorSelectionCriteria;
41
+ readonly hints?: readonly string[];
42
+ readonly attestation?: "none" | "indirect" | "direct" | "enterprise";
43
+ readonly attestationFormats?: readonly string[];
44
+ readonly extensions?: Readonly<Record<string, unknown>>;
45
+ };
46
+ /** The options of `navigator.credentials.get({ publicKey })` as JSON (`PublicKeyCredential.parseRequestOptionsFromJSON` takes it). */
47
+ export type PublicKeyCredentialRequestOptionsJSON = {
48
+ readonly challenge: string;
49
+ readonly timeout?: number;
50
+ readonly rpId?: string;
51
+ readonly allowCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
52
+ readonly userVerification?: "required" | "preferred" | "discouraged";
53
+ readonly hints?: readonly string[];
54
+ readonly extensions?: Readonly<Record<string, unknown>>;
55
+ };
56
+ /** An authenticator's answer to `create()`, as `AuthenticatorAttestationResponse.toJSON()` gives it. */
57
+ export type AuthenticatorAttestationResponseJSON = {
58
+ readonly clientDataJSON: string;
59
+ readonly attestationObject: string;
60
+ readonly authenticatorData?: string;
61
+ readonly transports?: readonly string[];
62
+ readonly publicKey?: string;
63
+ readonly publicKeyAlgorithm?: number;
64
+ };
65
+ /** A new credential, as `PublicKeyCredential.toJSON()` gives it after `create()`. */
66
+ export type RegistrationResponseJSON = {
67
+ readonly id: string;
68
+ readonly rawId: string;
69
+ readonly response: AuthenticatorAttestationResponseJSON;
70
+ readonly authenticatorAttachment?: string | null;
71
+ readonly clientExtensionResults: Readonly<Record<string, unknown>>;
72
+ readonly type: "public-key";
73
+ };
74
+ /** An authenticator's answer to `get()`, as `AuthenticatorAssertionResponse.toJSON()` gives it. */
75
+ export type AuthenticatorAssertionResponseJSON = {
76
+ readonly clientDataJSON: string;
77
+ readonly authenticatorData: string;
78
+ readonly signature: string;
79
+ readonly userHandle?: string | null;
80
+ };
81
+ /** An assertion, as `PublicKeyCredential.toJSON()` gives it after `get()`. */
82
+ export type AuthenticationResponseJSON = {
83
+ readonly id: string;
84
+ readonly rawId: string;
85
+ readonly response: AuthenticatorAssertionResponseJSON;
86
+ readonly authenticatorAttachment?: string | null;
87
+ readonly clientExtensionResults: Readonly<Record<string, unknown>>;
88
+ readonly type: "public-key";
89
+ };
90
+ /** A credential as the relying party keeps it: its id and COSE public key (base64url), its algorithm and its last signature counter. */
91
+ export type StoredCredential = {
92
+ readonly id: string;
93
+ readonly publicKey: string;
94
+ readonly alg: number;
95
+ readonly signCount: number;
96
+ };
97
+ /** What a verified registration gives the relying party to keep. */
98
+ export type VerifiedRegistration = {
99
+ /** The credential's id, base64url. */
100
+ readonly credentialId: string;
101
+ /** The credential's public key as its CBOR `COSE_Key`, base64url. */
102
+ readonly publicKey: string;
103
+ /** Its COSE algorithm: -7 (ES256) or -8 (EdDSA). */
104
+ readonly alg: number;
105
+ readonly signCount: number;
106
+ readonly userVerified: boolean;
107
+ /** Whether the credential is backed up (synced, a passkey): the BS flag. */
108
+ readonly backedUp: boolean;
109
+ /** Whether it may be backed up: the BE flag. */
110
+ readonly backupEligible: boolean;
111
+ /** The authenticator's AAGUID, as a UUID (all zeros under attestation `none`). */
112
+ readonly aaguid: string;
113
+ /** The attestation format the authenticator used (`none` or `packed`). */
114
+ readonly fmt: string;
115
+ readonly transports?: string[];
116
+ };
117
+ /** What a verified authentication gives: the counter to keep, and the flags. */
118
+ export type VerifiedAuthentication = {
119
+ readonly signCount: number;
120
+ readonly userVerified: boolean;
121
+ readonly backedUp: boolean;
122
+ };
123
+ /** The default time a ceremony may take: five minutes, within what Level 3 recommends where user verification is required. */
124
+ export declare const DEFAULT_TIMEOUT_MS = 300000;
125
+ /**
126
+ * The options for registering a credential: ES256 and EdDSA offered, a discoverable credential preferred, user verification required, no
127
+ * attestation asked for, and the credentials the user already has excluded. A challenge shorter than 16 bytes or a user id longer than 64
128
+ * is a programming error and throws a `RangeError`.
129
+ */
130
+ export declare function registrationOptions(o: {
131
+ readonly rpId: string;
132
+ readonly rpName: string;
133
+ readonly user: {
134
+ readonly id: string;
135
+ readonly name: string;
136
+ readonly displayName: string;
137
+ };
138
+ readonly challenge: string;
139
+ readonly excludeCredentials?: readonly string[];
140
+ readonly timeoutMs?: number;
141
+ }): PublicKeyCredentialCreationOptionsJSON;
142
+ /** The options for authenticating: user verification required, and the credentials allowed where the user is known (none for a passkey's discoverable sign-in). */
143
+ export declare function authenticationOptions(o: {
144
+ readonly rpId: string;
145
+ readonly challenge: string;
146
+ readonly allowCredentials?: readonly string[];
147
+ readonly timeoutMs?: number;
148
+ }): PublicKeyCredentialRequestOptionsJSON;
149
+ /** The flags of authenticator data (WebAuthn §6.1). */
150
+ export declare const FLAGS: {
151
+ readonly up: 1;
152
+ readonly uv: 4;
153
+ readonly be: 8;
154
+ readonly bs: 16;
155
+ readonly at: 64;
156
+ readonly ed: 128;
157
+ };
158
+ /** Authenticator data as read (WebAuthn §6.1). */
159
+ export type AuthenticatorData = {
160
+ readonly rpIdHash: Uint8Array;
161
+ readonly flags: number;
162
+ readonly userPresent: boolean;
163
+ readonly userVerified: boolean;
164
+ readonly backupEligible: boolean;
165
+ readonly backedUp: boolean;
166
+ readonly signCount: number;
167
+ /** The attested credential data, where the AT flag says it is there. */
168
+ readonly attested?: {
169
+ readonly aaguid: Uint8Array;
170
+ readonly credentialId: Uint8Array;
171
+ readonly publicKey: Uint8Array;
172
+ };
173
+ /** The extension outputs, where the ED flag says they are there. */
174
+ readonly extensions?: ReadonlyMap<CborKey, CborValue>;
175
+ };
176
+ /** Authenticator data read: the RP ID hash, the flags, the counter, the attested credential (its COSE key's bytes as given) and extensions; every byte accounted for. */
177
+ export declare function parseAuthenticatorData(bytes: Uint8Array): Result<AuthenticatorData, string>;
178
+ /** Client data as read (WebAuthn §5.8.1). */
179
+ export type ClientData = {
180
+ readonly type: string;
181
+ readonly challenge: string;
182
+ readonly origin: string;
183
+ readonly crossOrigin?: boolean;
184
+ readonly topOrigin?: string;
185
+ };
186
+ /** Client data JSON (its bytes, UTF-8) read. */
187
+ export declare function parseClientData(bytes: Uint8Array): Result<ClientData, string>;
188
+ /**
189
+ * A registration verified (WebAuthn §7.1): the client data, the attestation object, the authenticator data and the credential's key; what
190
+ * to keep, or why it is refused.
191
+ */
192
+ export declare function verifyRegistration(o: {
193
+ readonly response: RegistrationResponseJSON;
194
+ readonly expectedChallenge: string;
195
+ readonly expectedOrigin: string | readonly string[];
196
+ readonly rpId: string;
197
+ }): Promise<Result<VerifiedRegistration, string>>;
198
+ /**
199
+ * An authentication verified (WebAuthn §7.2) against the credential kept at registration: the client data, the authenticator data, the
200
+ * signature and the counter; the counter and flags to keep, or why it is refused.
201
+ */
202
+ export declare function verifyAuthentication(o: {
203
+ readonly response: AuthenticationResponseJSON;
204
+ readonly expectedChallenge: string;
205
+ readonly expectedOrigin: string | readonly string[];
206
+ readonly rpId: string;
207
+ readonly credential: StoredCredential;
208
+ }): Promise<Result<VerifiedAuthentication, string>>;
209
+ /** JSON from a browser read as a `RegistrationResponseJSON`, or why it is not one: the boundary before `verifyRegistration`. */
210
+ export declare function parseRegistrationResponse(input: unknown): Result<RegistrationResponseJSON, string>;
211
+ /** JSON from a browser read as an `AuthenticationResponseJSON`, or why it is not one: the boundary before `verifyAuthentication`. */
212
+ export declare function parseAuthenticationResponse(input: unknown): Result<AuthenticationResponseJSON, string>;
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Display width: how many columns of a terminal a text takes, and a text cut to a number of columns (commons 0006-signals FR-023). An
3
+ * escape sequence takes none and is never split; a grapheme (what a person sees as one character, found with `Intl.Segmenter`) is never
4
+ * split either; a wide character or an emoji takes two columns.
5
+ *
6
+ * The width of a grapheme is an approximation of what terminals do (as `wcwidth` and the `string-width` package approximate it):
7
+ * - a control character, a combining mark, a format character (such as the zero-width joiner) or a variation selector alone: 0;
8
+ * - an emoji: 2 when it is shown as an emoji, which is when its first code point has the `Emoji_Presentation` property (✅ ❌ 👉), when
9
+ * it carries the emoji variation selector U+FE0F (⏭️ ⏹️ ⚠️, keycaps such as 1️⃣), or when it is a zero-width-joiner sequence (one glyph
10
+ * of two columns, however many code points it joins); the text variation selector U+FE0E makes it 1;
11
+ * - an East Asian Wide or Fullwidth character (CJK ideographs, kana, Hangul syllables, fullwidth forms): 2, by the ranges in `WIDE`,
12
+ * which follow Unicode's `EastAsianWidth.txt` in blocks rather than code point by code point (JavaScript has no property escape for it);
13
+ * - anything else: 1. Ambiguous-width characters (Greek, box drawing) count 1, as a terminal in a Western locale shows them.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import { cutToWidth, displayWidth } from "./width.js";
18
+ * displayWidth("✅ 测试"); // 7
19
+ * cutToWidth("✅ 测试", 6); // "✅ 测"
20
+ * cutToWidth("\u001b[31mfailed badly\u001b[0m", 7, "…"); // "\u001b[31mfailed…\u001b[0m"
21
+ * ```
22
+ *
23
+ * @module
24
+ */
25
+ /** A piece of a text: an escape sequence, or a run of text between them. */
26
+ export type Token = {
27
+ readonly kind: "escape";
28
+ readonly text: string;
29
+ } | {
30
+ readonly kind: "text";
31
+ readonly text: string;
32
+ };
33
+ /** A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again. */
34
+ export declare function tokens(text: string): readonly Token[];
35
+ /** The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by `Intl.Segmenter`). */
36
+ export declare function graphemes(text: string): readonly string[];
37
+ /** The columns one grapheme takes: 0, 1 or 2 (see the module's rules). */
38
+ export declare function graphemeWidth(grapheme: string): 0 | 1 | 2;
39
+ /** The columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none. */
40
+ export declare function displayWidth(text: string): number;
41
+ /** A text split in two at a number of columns. */
42
+ export type Split = {
43
+ /** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
44
+ readonly head: string;
45
+ /** The rest: `head + tail` is the text. */
46
+ readonly tail: string;
47
+ };
48
+ /**
49
+ * A text split where it reaches `width` columns, between two graphemes or escape sequences, never inside one: a wide character that would
50
+ * cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.
51
+ */
52
+ export declare function splitAtWidth(text: string, width: number): Split;
53
+ /** The parameters of an SGR sequence (`ESC [ ... m`), or undefined for another sequence. */
54
+ export declare function sgrParams(escape: string): readonly number[] | undefined;
55
+ /** The SGR sequence that turns every style off. */
56
+ export declare const RESET: string;
57
+ /**
58
+ * A text cut to at most `width` columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the
59
+ * `ellipsis` (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a
60
+ * colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than
61
+ * `width` is left out.
62
+ */
63
+ export declare function cutToWidth(text: string, width: number, ellipsis?: string): string;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * XML as a typed tree of elements and text, written with every value escaped (no document is a template of values) and read with no
3
+ * outside package (commons 0005-typescript-runtime FR-032). The reader takes elements, attributes in either quote, the five named entities
4
+ * and character references, CDATA, comments, processing instructions and the XML declaration, checks that every element is closed by its
5
+ * own name, and refuses a document type with an internal subset, so no entity is ever expanded (no "billion laughs", no external entity).
6
+ * Names are kept as written (`dc:title`); the finders match a name with or without its prefix. Taken from erga's `lib/ts/xml`, whose
7
+ * reader was `@std/xml`.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * import { el, readXml, textOf, writeXml } from "./xml.js";
12
+ * const doc = writeXml(el("note", [el("to", ["Ada & Charles"])], [["lang", "en"]]));
13
+ * // '<?xml version="1.0" encoding="UTF-8"?>\n<note lang="en"><to>Ada &amp; Charles</to></note>'
14
+ * const back = readXml(doc);
15
+ * if (back.kind === "ok") textOf(back.value); // "Ada & Charles"
16
+ * ```
17
+ *
18
+ * @module
19
+ */
20
+ import { type Result } from "@intellectual-frontiers/core";
21
+ /** An element: its name as written, its attributes in order, and its children. */
22
+ export type XmlElement = {
23
+ readonly kind: "element";
24
+ readonly name: string;
25
+ readonly attributes: readonly (readonly [string, string])[];
26
+ readonly children: readonly XmlNode[];
27
+ };
28
+ /** Text, its entities and references already replaced. */
29
+ export type XmlText = {
30
+ readonly kind: "text";
31
+ readonly text: string;
32
+ };
33
+ /** A node of an XML document. */
34
+ export type XmlNode = XmlElement | XmlText;
35
+ /** What an element may be given as a child: a node, or a value written as text; `undefined` gives nothing. */
36
+ export type XmlChild = XmlNode | string | number | boolean | undefined;
37
+ /** An element. */
38
+ export declare function el(name: string, children?: readonly XmlChild[], attributes?: readonly (readonly [string, string])[]): XmlElement;
39
+ /** An element holding one value, or nothing where the value is absent. */
40
+ export declare function leaf(name: string, value: string | number | boolean | undefined): XmlElement | undefined;
41
+ /** A value as XML text or an attribute's value: `&`, `<`, `>`, `"` and `'` escaped, and the characters XML 1.0 forbids removed. */
42
+ export declare function escapeXml(s: string): string;
43
+ /** A node as XML text, with no declaration. */
44
+ export declare function writeNode(n: XmlNode): string;
45
+ /** A whole document: the XML declaration, then its root. */
46
+ export declare function writeXml(root: XmlElement): string;
47
+ /** Where a text stops being XML this reader takes, and why. Lines and columns count from 1. */
48
+ export type XmlError = {
49
+ readonly kind: "xml";
50
+ readonly line: number;
51
+ readonly column: number;
52
+ readonly message: string;
53
+ };
54
+ /** How to read: whether text that is only white space between elements is kept (it is dropped by default). */
55
+ export type ReadXmlOptions = {
56
+ readonly keepWhitespace?: boolean;
57
+ };
58
+ /** A document read: its root element; or where and why it is not XML this reader takes. */
59
+ export declare function readXml(text: string, options?: ReadXmlOptions): Result<XmlElement, XmlError>;
60
+ /** An XML error as one line: `3:14: expected a name`. */
61
+ export declare function formatXmlError(e: XmlError): string;
62
+ /** A name without its prefix: `title` for `dc:title`. */
63
+ export declare function localName(name: string): string;
64
+ /** The child elements of a node named `name` (with or without a prefix). */
65
+ export declare function children(n: XmlNode, name: string): readonly XmlElement[];
66
+ /** The first child element named `name`. */
67
+ export declare function child(n: XmlNode, name: string): XmlElement | undefined;
68
+ /** Every element below a node named `name`, in document order. */
69
+ export declare function descendants(n: XmlNode, name: string): readonly XmlElement[];
70
+ /** All the text a node holds. */
71
+ export declare function textOf(n: XmlNode | undefined): string;
72
+ /** An attribute's value, by its name with or without a prefix. */
73
+ export declare function attribute(n: XmlNode | undefined, name: string): string | undefined;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * YAML 1.2 for data (commons 0005-typescript-runtime FR-038), read and written with no outside package. The reader takes what data files,
3
+ * front matter and configuration use: block mappings and sequences (a sequence may sit at its key's indentation, and a mapping may begin
4
+ * on a sequence's dash), flow collections over several lines, plain scalars folded over several lines, single- and double-quoted scalars
5
+ * with every escape of YAML 1.2, literal and folded block scalars with their chomping and indentation indicators, comments and one
6
+ * document between `---` and `...`. Plain scalars resolve by the core schema (null, booleans, integers in decimal, octal and hexadecimal,
7
+ * floats with `.inf` and `.nan`) or, with the failsafe schema, stay text. It refuses, with the line and column and the reason, what makes
8
+ * data ambiguous or unsafe to read: anchors and aliases (and so no "billion laughs"), tags, complex keys, directives, more than one
9
+ * document, a key given twice and a tab used for indentation. The writer gives block YAML that the reader reads back as the same value.
10
+ * Replaces `@std/yaml` in erga.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { parseYaml, toYaml } from "./yaml.js";
15
+ * parseYaml("name: skill\ntags: [a, b]\nsteps:\n - run: build\n times: 2\n");
16
+ * // { kind: "ok", value: { name: "skill", tags: ["a", "b"], steps: [{ run: "build", times: 2 }] } }
17
+ * toYaml({ name: "skill", on: true }); // "name: skill\non: true\n" (YAML 1.2: "on" is only text)
18
+ * ```
19
+ *
20
+ * @module
21
+ */
22
+ import type { Json } from "./json5.js";
23
+ import { type Result } from "@intellectual-frontiers/core";
24
+ /** Where a text stops being YAML this reader takes, and why. Lines and columns count from 1. */
25
+ export type YamlError = {
26
+ readonly kind: "yaml";
27
+ readonly line: number;
28
+ readonly column: number;
29
+ readonly message: string;
30
+ };
31
+ /** A YAML error as one line: `3:14: anchors and aliases are not read`. */
32
+ export declare function formatYamlError(e: YamlError): string;
33
+ /** How plain scalars resolve: by YAML 1.2's core schema (the default), or all as text (failsafe). */
34
+ export type YamlOptions = {
35
+ readonly schema?: "core" | "failsafe";
36
+ };
37
+ /** A plain scalar resolved by YAML 1.2's core schema. */
38
+ export declare function resolveCore(s: string): Json;
39
+ /** A YAML text read as a JSON value (an empty document is `null`), or where and why it is not YAML this reader takes. */
40
+ export declare function parseYaml(text: string, options?: YamlOptions): Result<Json, YamlError>;
41
+ /** Whether text can be written as a plain scalar and read back as the same text by the core schema. */
42
+ export declare function isPlainSafe(s: string): boolean;
43
+ /** A value as block YAML, ending in a line break: mappings and sequences by indentation, text plain where it reads back the same, else double-quoted. */
44
+ export declare function toYaml(value: Json): string;
@@ -0,0 +1,149 @@
1
+ /**
2
+ * How a typed client reaches a system over HTTP (commons 0005-typescript-runtime FR-040): a transport, live (`fetch`) or recorded (the
3
+ * exchanges a test keeps, so it reaches no host), and over it the guards and helpers every client otherwise rewrites: a read-only guard
4
+ * (safe methods only, POST to the token endpoints named, and the POSTs a predicate says only read, FR-066), AWS Signature Version 4 on each
5
+ * request (FR-069), backoff on 429 and 503 that honours `Retry-After`, a JSON read decoded at the boundary with typed failures (a denied
6
+ * call is told apart, so a caller can record a gap instead of failing), and every item of a list that pages by `Link: rel="next"` or by a
7
+ * cursor in the body. A request that carries a credential is refused before it is sent unless the transport is made to allow it, so a
8
+ * harness whose proxy injects credentials never sends one by mistake. Taken from erga's `lib/ts/http-client` and Stolos's connector SDK
9
+ * (`src/archon/connect/sdk.ts`, `connector.ts`).
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import { array, object, string } from "@intellectual-frontiers/core";
14
+ * import { getJson, liveTransport, withBackoff } from "./http-client.js";
15
+ * const http = withBackoff(liveTransport());
16
+ * const repo = await getJson(http, "https://api.github.com/repos/oven-sh/bun", object({ full_name: string }));
17
+ * ```
18
+ *
19
+ * @module
20
+ */
21
+ import { type Decoder, type Result } from "@intellectual-frontiers/core";
22
+ import { type AwsCredentials } from "../kernel/sigv4.js";
23
+ /** A request a client makes. */
24
+ export type OutRequest = {
25
+ readonly method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
26
+ readonly url: string;
27
+ readonly headers: Readonly<Record<string, string>>;
28
+ readonly body?: string;
29
+ /** Read the answer as bytes (`Exchange.bytes`), for an artifact that is not text (a tarball, a zip); the text `body` of the answer is then empty. */
30
+ readonly binary?: boolean;
31
+ };
32
+ /** One exchange: a request and what answered it. */
33
+ export type Exchange = {
34
+ readonly method: OutRequest["method"];
35
+ readonly url: string;
36
+ readonly status: number;
37
+ /** The headers kept: the content type, paging, rate limits and `Retry-After`. */
38
+ readonly headers: Readonly<Record<string, string>>;
39
+ readonly body: string;
40
+ /** The answer's bytes: present where the request asked for `binary` (a recorded exchange of an artifact holds them). */
41
+ readonly bytes?: Uint8Array;
42
+ };
43
+ /** Why a request got no answer at all (a refusal before it was sent, or the network). */
44
+ export type TransportError = {
45
+ readonly kind: "refused";
46
+ readonly message: string;
47
+ } | {
48
+ readonly kind: "network";
49
+ readonly message: string;
50
+ };
51
+ /** A way to reach a system. */
52
+ export type Transport = {
53
+ readonly kind: "live" | "recorded";
54
+ readonly send: (r: OutRequest) => Promise<Result<Exchange, TransportError>>;
55
+ };
56
+ /** The headers a credential travels in. */
57
+ export declare const CREDENTIAL_HEADERS: readonly string[];
58
+ /** Why a request may not be sent where credentials are refused: it carries one in a header or in its query. Undefined where it carries none. */
59
+ export declare function carriesCredential(r: OutRequest): string | undefined;
60
+ /** How the live transport sends. */
61
+ export type LiveOptions = {
62
+ /** The `fetch` to use (the platform's by default). */
63
+ readonly fetch?: typeof fetch;
64
+ /** Refuse a request that carries a credential (the default), or send it. */
65
+ readonly credentials?: "refuse" | "allow";
66
+ /** The `User-Agent` said to every system: a generic name, never a person's. */
67
+ readonly userAgent?: string;
68
+ /** No answer within this many seconds fails the request (30 by default). */
69
+ readonly timeoutSeconds?: number;
70
+ };
71
+ /** The live transport, over `fetch`. */
72
+ export declare function liveTransport(options?: LiveOptions): Transport;
73
+ /** A transport that answers from recorded exchanges, by method and URL, and refuses a request it has none for, naming it. */
74
+ export declare function recordedTransport(exchanges: readonly Exchange[]): Transport;
75
+ /**
76
+ * Whether a `POST` only reads (FR-066): a GraphQL query, a search, a JSON API's `Describe` and `Get` actions. It is given the whole
77
+ * request (method, URL, headers and body), as an action may be named in a header (`x-amz-target`) or the body.
78
+ */
79
+ export type ReadPost = (r: OutRequest) => boolean;
80
+ /**
81
+ * A transport that sends only safe methods (GET, HEAD, ...), POST to URLs that start with one of `tokenEndpoints`, and the POSTs that
82
+ * `readPost` says only read (FR-066). Every other request (PUT, PATCH, DELETE, any other POST) is refused without being sent.
83
+ */
84
+ export declare function readOnly(t: Transport, tokenEndpoints?: readonly string[], readPost?: ReadPost): Transport;
85
+ /** How {@link withSigV4} signs. */
86
+ export type SigV4TransportOptions = {
87
+ readonly credentials: AwsCredentials;
88
+ readonly region: string;
89
+ readonly service: string;
90
+ /** The clock read as each request is sent (`new Date()` by default; a test gives its own). */
91
+ readonly now?: () => Date;
92
+ /** Sign `UNSIGNED-PAYLOAD` instead of the body's hash (S3 allows it). */
93
+ readonly unsignedPayload?: boolean;
94
+ };
95
+ /**
96
+ * A transport that signs each request by AWS Signature Version 4 (FR-069, by the kernel's `sigv4`, FR-068) when it is sent. A signed
97
+ * request carries a credential, so the live transport under it must be made with `credentials: "allow"`, or it refuses the request.
98
+ */
99
+ export declare function withSigV4(t: Transport, options: SigV4TransportOptions): Transport;
100
+ /** How long to back off. */
101
+ export type BackoffOptions = {
102
+ /** Tries after the first (3 by default). */
103
+ readonly retries?: number;
104
+ /** How a wait is spent (a timer by default; a test passes one that returns at once). */
105
+ readonly pause?: (ms: number) => Promise<void>;
106
+ /** The longest wait, whatever `Retry-After` asks (60 s by default). */
107
+ readonly capMs?: number;
108
+ };
109
+ /** A transport that waits and tries again on 429 and 503: as long as `Retry-After` asks (up to the cap), else 1, 2, 4 seconds. */
110
+ export declare function withBackoff(t: Transport, options?: BackoffOptions): Transport;
111
+ /** Why a JSON read failed. */
112
+ export type ReadError = TransportError | {
113
+ readonly kind: "denied";
114
+ readonly status: 401 | 403;
115
+ readonly url: string;
116
+ } | {
117
+ readonly kind: "status";
118
+ readonly status: number;
119
+ readonly url: string;
120
+ } | {
121
+ readonly kind: "decode";
122
+ readonly url: string;
123
+ readonly message: string;
124
+ };
125
+ /** A read error as one sentence; never a header or a body, so no credential or personal datum is said. */
126
+ export declare function formatReadError(e: ReadError): string;
127
+ /** A GET whose JSON body is decoded, with the exchange; 401 and 403 are `denied`, any other status from 400 up is `status`. */
128
+ export declare function getExchange<T>(t: Transport, url: string, decoder: Decoder<T>, headers?: Readonly<Record<string, string>>): Promise<Result<{
129
+ readonly value: T;
130
+ readonly exchange: Exchange;
131
+ }, ReadError>>;
132
+ /** A GET whose JSON body is decoded. */
133
+ export declare function getJson<T>(t: Transport, url: string, decoder: Decoder<T>, headers?: Readonly<Record<string, string>>): Promise<Result<T, ReadError>>;
134
+ /** Every page of a list that pages by `Link: <...>; rel="next"`, at most `maxPages` (200 by default); the first failure ends it, as an error. */
135
+ export declare function linkPages<T>(t: Transport, url: string, item: Decoder<T>, options?: {
136
+ readonly headers?: Readonly<Record<string, string>>;
137
+ readonly maxPages?: number;
138
+ }): AsyncGenerator<T, Result<number, ReadError>>;
139
+ /** Every item of a list that pages by a cursor in its body: `items` takes a page's items, `next` the next page's URL or undefined. */
140
+ export declare function cursorPages<B, T>(t: Transport, first: string, page: Decoder<B>, items: (body: B) => readonly T[], next: (body: B, url: string) => string | undefined, options?: {
141
+ readonly headers?: Readonly<Record<string, string>>;
142
+ readonly maxPages?: number;
143
+ }): AsyncGenerator<T, Result<number, ReadError>>;
144
+ /** A recorded exchange read from the JSON5 text `recordedText` writes, or why it is not one. */
145
+ export declare function decodeRecorded(text: string): Result<Exchange, string>;
146
+ /** The text a recorded exchange is kept in: a comment that says where and when it was recorded, then the exchange as JSON5. */
147
+ export declare function recordedText(x: Exchange, note: string): string;
148
+ /** Headers that give a bearer token (for a transport made to allow credentials). */
149
+ export declare function bearer(token: string, scheme?: string): Readonly<Record<string, string>>;