@orkestrel/scaffold 0.0.119 → 0.0.120
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +15 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +27 -26
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +136 -136
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/manifest.json +39 -464
- package/dist/src/core/index.cjs +162 -177
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +151 -166
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +25 -25
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -50
- package/dist/src/server/index.d.ts +50 -50
- package/dist/src/server/index.js +26 -26
- package/dist/src/server/index.js.map +1 -1
- package/package.json +9 -9
package/dist/host/guides/msg.md
CHANGED
|
@@ -25,7 +25,8 @@ error still propagates. Reach for `new MSG()` directly when a thrown
|
|
|
25
25
|
`MSGError` is the control flow you want:
|
|
26
26
|
|
|
27
27
|
```ts
|
|
28
|
-
import {
|
|
28
|
+
import { isSuccess } from '@orkestrel/contract'
|
|
29
|
+
import { createMSG } from '@orkestrel/msg'
|
|
29
30
|
|
|
30
31
|
const result = createMSG({ bytes, name: 'message.eml' })
|
|
31
32
|
if (isSuccess(result)) {
|
|
@@ -37,13 +38,11 @@ if (isSuccess(result)) {
|
|
|
37
38
|
|
|
38
39
|
### Types
|
|
39
40
|
|
|
40
|
-
From [`types.ts`](../src/core/types.ts).
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
[`contract.md`](contract.md)); this package's `success` / `failure` / `isSuccess` / `isFailure`
|
|
46
|
-
wrap them and do not re-export the types.
|
|
41
|
+
From [`types.ts`](../src/core/types.ts). `MSGInterface`'s call-signature members are documented
|
|
42
|
+
under [`## Methods`](#methods). `Success`, `Failure`, and `Result` are the originating types from
|
|
43
|
+
`@orkestrel/contract` (mirrored at [`contract.md`](contract.md)), which also exports the
|
|
44
|
+
`success`, `failure`, `isSuccess`, and `isFailure` functions; import each from there, because this
|
|
45
|
+
package re-exports none of them.
|
|
47
46
|
|
|
48
47
|
| Name | Kind | Signature | Summary |
|
|
49
48
|
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -74,8 +73,6 @@ wrap them and do not re-export the types.
|
|
|
74
73
|
|
|
75
74
|
The CFB layout offsets and sizes, the MSG/EML sniffing tables, the MAPI field name mappings, and the burner's geometry, from [`constants.ts`](../src/core/constants.ts). None of them carries runtime behavior. Every value is a fixed offset, a size, or a lookup table that the parsing and burning code in `MSG.ts`, `parsers.ts`, and `helpers.ts` reads.
|
|
76
75
|
|
|
77
|
-
A `Shape` cell holds the constant's declared type.
|
|
78
|
-
|
|
79
76
|
| Name | Kind | Signature | Summary |
|
|
80
77
|
| ----------------------------------- | ----- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
78
|
| `MSG_FILE_HEADER` | const | `readonly number[]` | Holds the 8-byte CFB/OLE2 magic signature (`D0 CF 11 E0 A1 B1 1A E1`) a `.msg` file must open with. |
|
|
@@ -163,44 +160,35 @@ It refuses transparent proxies, unbranded errors, and plain objects carrying the
|
|
|
163
160
|
|
|
164
161
|
### Helpers
|
|
165
162
|
|
|
166
|
-
Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the
|
|
167
|
-
|
|
168
|
-
| Name
|
|
169
|
-
|
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `decodeMIMEEncoding` | function | `(body: string, encoding: string) => Uint8Array` | Decodes a MIME body — `base64`, `quoted-printable`, or passthrough — into raw bytes, throwing on invalid Base64. |
|
|
193
|
-
| `decodeMIMEText` | function | `(body: string, encoding: string, charset: string) => string` | Decodes a MIME body to text through `decodeMIMEEncoding` and `resolveEncoding`, taking the charset from a free-form label. |
|
|
194
|
-
| `decodeMIMEWords` | function | `(text: string) => string` | Decodes the RFC 2047 encoded words (`=?charset?B/Q?...?=`) in a header value, reading the Base64 (`B`) and quoted-printable (`Q`) forms alike. |
|
|
195
|
-
| `formatEmailAddress` | function | `(name: string \| undefined, email: string \| undefined) => string` | Formats a display name and an email address into `"Name <email>"`, or into whichever half is present. |
|
|
196
|
-
| `inferExtension` | function | `(mimeType?: string, fileName?: string) => string` | Infers an attachment's file extension from its file name or its MIME type, returning the extension with its leading dot and falling back to `.bin`. |
|
|
163
|
+
Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the CFB byte/string/UUID readers and magic check `MSG.ts` composes, the format sniffer, and the MIME/text codecs `parsers.ts` and `shapers.ts` compose.
|
|
164
|
+
|
|
165
|
+
| Name | Kind | Signature | Summary |
|
|
166
|
+
| ------------------------ | -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
167
|
+
| `truncateAtNull` | function | `(text: string) => string` | Truncates a string at its first `\0` character. |
|
|
168
|
+
| `readUTF16String` | function | `(view: DataView, offset: number, charCount: number) => string` | Reads a UTF-16LE string out of a `DataView`, throwing when the requested range exceeds the view's bounds. |
|
|
169
|
+
| `decodeText` | function | `(bytes: Uint8Array, encoding?: MSGEncoding) => string` | Decodes bytes into a string with a pure-ES decoder, dispatching on the named encoding. Default: `windows-1252`. |
|
|
170
|
+
| `fileTimeToUTCString` | function | `(low: number, high: number) => string` | Converts a Windows FILETIME (100-ns ticks since 1601-01-01) to a UTC date string. |
|
|
171
|
+
| `toHexLower` | function | `(value: number, length: number) => string` | Converts a number to a zero-padded lowercase hex string of the requested digit count. |
|
|
172
|
+
| `readMicrosoftUUID` | function | `(bytes: Uint8Array, offset: number) => string` | Reads a mixed-endian Microsoft UUID starting at an offset in a byte array, throwing past the array's bounds. |
|
|
173
|
+
| `roundUpToMultiple` | function | `(value: number, boundary: number) => number` | Rounds a value up to the nearest multiple of a boundary, which must be a power of 2. |
|
|
174
|
+
| `computeSectors` | function | `(bytes: number, sectorSize: number) => number` | Computes how many sectors of a given size hold a byte count, answering 0 for a count at or below zero. |
|
|
175
|
+
| `compareCFBName` | function | `(a: string, b: string) => number` | Orders two directory names as the compound file format requires, comparing by UTF-16 length first and then by uppercased code points. |
|
|
176
|
+
| `isMSGFile` | function | `(view: DataView) => boolean` | Reports whether a `DataView`'s first 8 bytes match the CFB magic signature. |
|
|
177
|
+
| `decodeForgivingBase64` | function | `(text: string) => Uint8Array` | Decodes a Base64 string into raw bytes without relying on `atob`, ignoring ASCII whitespace and tolerating missing padding. |
|
|
178
|
+
| `encodeLossyUTF8` | function | `(text: string) => Uint8Array` | Encodes a string into UTF-8 bytes, pairing surrogates and encoding a lone (unpaired) surrogate as U+FFFD. |
|
|
179
|
+
| `decodeLossyUTF8` | function | `(bytes: Uint8Array) => string` | Decodes UTF-8 bytes into a string WHATWG-style: an invalid byte sequence decodes as U+FFFD rather than throwing. |
|
|
180
|
+
| `decodeLossyWindows1252` | function | `(bytes: Uint8Array) => string` | Decodes Windows-1252 bytes into a string, resolving the `0x80`\-`0x9F` range through `WINDOWS_1252_HIGH` and otherwise matching `decodeLatin1` from `@orkestrel/codec`. |
|
|
181
|
+
| `resolveEncoding` | function | `(label: string \| undefined) => MSGEncoding` | Resolves a free-form charset label, as a MIME `charset` parameter carries it, to a supported `MSGEncoding`, falling back to `FALLBACK_CHARSET`'s encoding for an unrecognized or absent label. |
|
|
182
|
+
| `detectFormat` | function | `(name: string \| undefined, mime: string \| undefined) => EmailFormat \| undefined` | Derives the `EmailFormat` from a file name, a MIME type, or both, answering `undefined` when neither hints at a format. |
|
|
183
|
+
| `parseMIMEHeaders` | function | `(text: string) => ReadonlyMap<string, MIMEHeader>` | Parses an RFC 2822 / MIME header block, folding continuation lines. |
|
|
184
|
+
| `decodeMIMEEncoding` | function | `(body: string, encoding: string) => Uint8Array` | Decodes a MIME body — `base64`, `quoted-printable`, or passthrough — into raw bytes, throwing on invalid Base64. |
|
|
185
|
+
| `decodeMIMEText` | function | `(body: string, encoding: string, charset: string) => string` | Decodes a MIME body to text through `decodeMIMEEncoding` and `resolveEncoding`, taking the charset from a free-form label. |
|
|
186
|
+
| `decodeMIMEWords` | function | `(text: string) => string` | Decodes the RFC 2047 encoded words (`=?charset?B/Q?...?=`) in a header value, reading the Base64 (`B`) and quoted-printable (`Q`) forms alike. |
|
|
187
|
+
| `formatEmailAddress` | function | `(name: string \| undefined, email: string \| undefined) => string` | Formats a display name and an email address into `"Name <email>"`, or into whichever half is present. |
|
|
188
|
+
| `inferExtension` | function | `(mimeType?: string, fileName?: string) => string` | Infers an attachment's file extension from its file name or its MIME type, returning the extension with its leading dot and falling back to `.bin`. |
|
|
197
189
|
|
|
198
190
|
```ts
|
|
199
191
|
import {
|
|
200
|
-
success,
|
|
201
|
-
failure,
|
|
202
|
-
isSuccess,
|
|
203
|
-
isFailure,
|
|
204
192
|
truncateAtNull,
|
|
205
193
|
readUTF16String,
|
|
206
194
|
fileTimeToUTCString,
|
|
@@ -210,11 +198,10 @@ import {
|
|
|
210
198
|
computeSectors,
|
|
211
199
|
compareCFBName,
|
|
212
200
|
isMSGFile,
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
decodeWindows1252,
|
|
201
|
+
decodeForgivingBase64,
|
|
202
|
+
encodeLossyUTF8,
|
|
203
|
+
decodeLossyUTF8,
|
|
204
|
+
decodeLossyWindows1252,
|
|
218
205
|
resolveEncoding,
|
|
219
206
|
detectFormat,
|
|
220
207
|
parseMIMEHeaders,
|
|
@@ -231,17 +218,14 @@ computeSectors(100, 64) // 2
|
|
|
231
218
|
compareCFBName('a', 'b') // negative
|
|
232
219
|
isMSGFile(new DataView(new Uint8Array(8).buffer)) // false — no CFB magic
|
|
233
220
|
detectFormat('message.eml', undefined) // 'eml'
|
|
234
|
-
|
|
235
|
-
isFailure(failure(new Error())) // true
|
|
236
|
-
decodeLatin1(new Uint8Array([65])) // 'A'
|
|
237
|
-
decodeWindows1252(new Uint8Array([65])) // 'A'
|
|
221
|
+
decodeLossyWindows1252(new Uint8Array([65])) // 'A'
|
|
238
222
|
resolveEncoding('utf-8') // 'utf-8'
|
|
239
223
|
formatEmailAddress('A', 'a@x.dev') // 'A <a@x.dev>'
|
|
240
224
|
inferExtension('image/png') // '.png'
|
|
241
225
|
decodeMIMEEncoding('aGk=', 'base64') // Uint8Array of 'hi'
|
|
242
226
|
decodeMIMEText('aGk=', 'base64', 'utf-8') // 'hi'
|
|
243
|
-
|
|
244
|
-
|
|
227
|
+
encodeLossyUTF8('hi') // Uint8Array
|
|
228
|
+
decodeLossyUTF8(new Uint8Array([65])) // 'A'
|
|
245
229
|
|
|
246
230
|
const view = new DataView(new Uint8Array([0x48, 0x00, 0x69, 0x00]).buffer)
|
|
247
231
|
readUTF16String(view, 0, 2) // 'Hi'
|
|
@@ -305,8 +289,6 @@ parseMIMEPart('Subject: Hi\n\nBody text') // MIMEPart — { headers, body: 'Body
|
|
|
305
289
|
|
|
306
290
|
The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError` validates the global Error instance, its package brand, its code, and its context.
|
|
307
291
|
|
|
308
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
309
|
-
|
|
310
292
|
| Name | Kind | Signature | Summary |
|
|
311
293
|
| ------------------- | -------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
312
294
|
| `isEmailFormat` | function | `(value: unknown) => value is EmailFormat` | Narrows an unknown value to a valid `EmailFormat`: a total from-unknown guard, true for `'eml'` and `'msg'`. |
|
|
@@ -366,10 +348,11 @@ From [`factories.ts`](../src/core/factories.ts).
|
|
|
366
348
|
|
|
367
349
|
#### Parse an email file and read its format
|
|
368
350
|
|
|
369
|
-
Narrows the `createMSG` `Result` with `isSuccess` before reading the parsed `chain`'s format.
|
|
351
|
+
Narrows the `createMSG` `Result` with `isSuccess` from `@orkestrel/contract` before reading the parsed `chain`'s format.
|
|
370
352
|
|
|
371
353
|
```ts
|
|
372
|
-
import {
|
|
354
|
+
import { isSuccess } from '@orkestrel/contract'
|
|
355
|
+
import { createMSG } from '@orkestrel/msg'
|
|
373
356
|
|
|
374
357
|
const result = createMSG(bytes)
|
|
375
358
|
if (isSuccess(result)) {
|
|
@@ -396,7 +379,8 @@ The public methods of the behavioral interfaces this package publishes. `options
|
|
|
396
379
|
| `attachment` | `MSGAttachment` | Reads attachment binary content by zero-based index, returning its `name` and `bytes`. |
|
|
397
380
|
|
|
398
381
|
```ts
|
|
399
|
-
import {
|
|
382
|
+
import { isSuccess } from '@orkestrel/contract'
|
|
383
|
+
import { createMSG } from '@orkestrel/msg'
|
|
400
384
|
|
|
401
385
|
const result = createMSG(bytes) // Uint8Array of a .msg file
|
|
402
386
|
if (isSuccess(result)) {
|
|
@@ -424,8 +408,8 @@ A caller extracting an embedded `.msg` attachment and burning it standalone goes
|
|
|
424
408
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), the `MSGInterface` ↔ `MSG` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Parse an email file and read its format` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
|
|
425
409
|
- [`tests/src/core/MSG.test.ts`](../tests/src/core/MSG.test.ts) — construction (`.eml` / `.msg` / malformed input), `chain`, `fields`, `attachment`, `burn`, and the embedded-`.msg` extraction path.
|
|
426
410
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createMSG`'s `Result` contract (`Success`/`Failure`, with parse failures surfaced as `Failure<MSGError>` rather than thrown).
|
|
427
|
-
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `isMSGFile` / `
|
|
428
|
-
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the
|
|
411
|
+
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `isMSGFile` / `decodeLossyUTF8` / `detectFormat` / `parseMIMEPart` / `extractMessage` / `extractMessageFromMSG`, incl. `MIME_MAX_DEPTH` cycle guarding.
|
|
412
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the CFB byte/string/UUID readers and the MIME/text codecs.
|
|
429
413
|
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — `burnCFB` validity, mini-stream/FAT/DIFAT boundaries, red-black directory ordering, cycle/name limits, and real-parser round trips.
|
|
430
414
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — `isEmailFormat` / `isEmailAttachment` / `isEmailMessage` / `isEmailChain` soundness on well-formed and malformed input.
|
|
431
415
|
- `MSGError` shape and `isMSGError` narrowing are covered across [`tests/src/core/MSG.test.ts`](../tests/src/core/MSG.test.ts), [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts), and [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — no standalone `errors.test.ts` file exists.
|
|
@@ -37,10 +37,6 @@ parser.clear() // drop any buffered partial - ready for a fresh stream
|
|
|
37
37
|
|
|
38
38
|
### Types
|
|
39
39
|
|
|
40
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?`
|
|
41
|
-
marking an optional member and `plus` introducing its call-signature members,
|
|
42
|
-
and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
43
|
-
|
|
44
40
|
| Name | Kind | Signature | Summary |
|
|
45
41
|
| ----------------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
42
|
| `NDJSONParserInterface` | interface | `{ parse(), clear() }` | Represents the stateful NDJSON (newline-delimited JSON) stream-parser contract a consumer holds — a `parse` that turns each string chunk into the complete records decoded so far, and a `clear` that drops the buffered partial line. |
|
package/dist/host/guides/pool.md
CHANGED
|
@@ -52,8 +52,6 @@ try {
|
|
|
52
52
|
|
|
53
53
|
### Guards
|
|
54
54
|
|
|
55
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
56
|
-
|
|
57
55
|
| Name | Kind | Signature | Summary |
|
|
58
56
|
| -------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
|
|
59
57
|
| `isPoolError` | function | `(value: unknown) => value is PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
|
|
@@ -62,8 +60,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
|
62
60
|
|
|
63
61
|
### Types
|
|
64
62
|
|
|
65
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
66
|
-
|
|
67
63
|
| Name | Kind | Signature | Summary |
|
|
68
64
|
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
69
65
|
| `PoolCode` | type | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'` | Names the machine-readable failure codes produced by `PoolError`. |
|