@orkestrel/scaffold 0.0.119 → 0.0.121
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 +19 -19
- 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 +52 -51
- 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/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- 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/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- 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/terminal.md +0 -26
- 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/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- 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 +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -65,24 +65,22 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
65
65
|
|
|
66
66
|
### Middlewares — node
|
|
67
67
|
|
|
68
|
-
| Name
|
|
69
|
-
|
|
|
70
|
-
| `createAssets`
|
|
71
|
-
| `createStatic`
|
|
72
|
-
| `createMultipart`
|
|
73
|
-
| `
|
|
68
|
+
| Name | Kind | Signature | Summary |
|
|
69
|
+
| ----------------------- | -------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation. |
|
|
71
|
+
| `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests. |
|
|
72
|
+
| `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery. |
|
|
73
|
+
| `createNodeCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather than dependent on the WHATWG `CompressionStream` global. This battery is the node-bound sibling of the core face's feature-detected `createCompression`, and both compose the same `compressResponse` skeleton. |
|
|
74
74
|
|
|
75
75
|
### Types
|
|
76
76
|
|
|
77
|
-
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 `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
78
|
-
|
|
79
77
|
| Name | Kind | Signature | Summary |
|
|
80
78
|
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
79
|
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
|
|
82
80
|
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
|
|
83
81
|
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
|
|
84
82
|
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
|
|
85
|
-
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each
|
|
83
|
+
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
|
|
86
84
|
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
|
|
87
85
|
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
|
|
88
86
|
| `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
|
|
@@ -117,14 +115,14 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
117
115
|
| `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware/server`) produces per uploaded file. |
|
|
118
116
|
| `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
|
|
119
117
|
| `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
|
|
120
|
-
| `
|
|
118
|
+
| `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
|
|
121
119
|
| `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
|
|
122
120
|
| `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
|
|
123
121
|
| `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
|
|
124
122
|
| `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
|
|
125
123
|
| `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
|
|
126
124
|
| `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
|
|
127
|
-
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures
|
|
125
|
+
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
|
|
128
126
|
| `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
|
|
129
127
|
| `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
|
|
130
128
|
| `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of the pure core's `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared core shape. |
|
|
@@ -166,8 +164,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
166
164
|
|
|
167
165
|
### Constants
|
|
168
166
|
|
|
169
|
-
A `Shape` cell holds the constant's declared type.
|
|
170
|
-
|
|
171
167
|
| Name | Kind | Signature | Summary |
|
|
172
168
|
| --------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
173
169
|
| `DEFAULT_COMPRESSION_THRESHOLD` | const | `1024` | Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. |
|
|
@@ -198,7 +194,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
198
194
|
| `DEFAULT_CSRF_SAFE_METHODS` | const | `readonly string[]` | Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). |
|
|
199
195
|
| `MULTIPART_STATUS` | const | `Readonly<Record<MultipartErrorCode, number>>` | Holds the HTTP status `createMultipart` renders for each `MultipartErrorCode`: `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415. |
|
|
200
196
|
| `MULTIPART_ERROR_BRAND` | const | `unique symbol` | Holds the `Symbol.for` brand `MultipartError` carries so `isMultipartError` recognizes an instance across duplicate copies of this package — a registry symbol rather than a module-local `Symbol()`, which would mint an unequal symbol per copy. |
|
|
201
|
-
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings
|
|
197
|
+
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings `createNodeCompression` offers — what `node:zlib` guarantees on every Node runtime, so this face never feature-detects. |
|
|
202
198
|
| `DEFAULT_STATIC_INDEX` | const | `"index.html"` | Names `'index.html'`, `createStatic`'s default directory-index filename. |
|
|
203
199
|
| `DEFAULT_STATIC_FALLBACK_EXCLUDE` | const | `"/api"` | Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. |
|
|
204
200
|
| `DEFAULT_STATIC_DOTFILES` | const | `NonNullable<StaticOptions['dotfiles']>` | Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. |
|
|
@@ -215,8 +211,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
215
211
|
|
|
216
212
|
### Shapers
|
|
217
213
|
|
|
218
|
-
A `Shape` cell holds the constant's declared type.
|
|
219
|
-
|
|
220
214
|
| Name | Kind | Signature | Summary |
|
|
221
215
|
| ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
216
|
| `sessionColumns` | const | `{ id: import("@orkestrel/contract").StringShape; session: import("@orkestrel/contract").JSONShape; seen: import("@orkestrel/contract").NumberShape; created: import("@orkestrel/contract").NumberShape; }` | Holds the `@orkestrel/database` column shape for a `SessionRow` table. Pass it as-is to `createDatabase({ tables: { sessions: sessionColumns } })` so an app declaring a durable session table never hand-writes the shape. |
|
|
@@ -237,7 +231,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
237
231
|
| `matchesUnbufferableResponse` | function | `(method: string, response: Response, skipHeader: string) => boolean` | Checks whether a response must skip the compression and ETag buffering pipeline — the shared cheap-skip predicate both batteries apply before ever touching `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or otherwise bodyless response, an `event-stream` response, and a response already carrying the header the caller is about to set. |
|
|
238
232
|
| `isCompressionNegotiated` | function | `(encoding: Encoding \| undefined) => encoding is Exclude<Encoding, 'identity'>` | Checks whether a negotiated `Accept-Encoding` outcome is worth acting on — `createCompression`'s negotiation-eligibility half of the skip list. |
|
|
239
233
|
| `rebuildResponse` | function | `(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]) => Response` | Rebuilds a `Response` around a replacement body while preserving its status/statusText — the buffered-response reconstruction shared by the compression and ETag batteries after they have consumed `response.arrayBuffer()`. |
|
|
240
|
-
| `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton
|
|
234
|
+
| `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton `createCompression` and `createNodeCompression` compose — response-body compression over a caller-supplied set of feature-detected codings. |
|
|
241
235
|
| `transferSessionState` | function | `(from: SessionInterface, to: SessionInterface) => void` | Copies every entry of one session's `state` into another — the regenerate state-carry `createSession`'s `control.regenerate()` applies. |
|
|
242
236
|
| `sessionExpired` | function | `(cursors: SessionCursors, now: number, limits: SessionLimits) => boolean` | Checks whether a session has aged past its idle timeout or absolute lifetime as of `now` — the pure expiry predicate `MemorySessionStore` delegates to. |
|
|
243
237
|
| `snapshotSession` | function | `(session: SessionInterface) => SessionSnapshot` | Snapshots a session's `state` into a plain, serializable record — the projection a durable store's `set` writes to disk. |
|
|
@@ -250,8 +244,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
250
244
|
|
|
251
245
|
Each guard in the following table is total: it accepts any input, returns `false` off-shape, and never throws.
|
|
252
246
|
|
|
253
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
254
|
-
|
|
255
247
|
| Name | Kind | Signature | Summary |
|
|
256
248
|
| ------------------ | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
249
|
| `isSession` | function | `(value: unknown) => value is SessionInterface` | Determines whether a value implements `SessionInterface` — a total structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`, and `clear` mutators. Prototype-agnostic — accepts a plain object, a null-prototype object, and a class instance (a real `Session`), because a restored or stored session is routinely a class instance rather than a literal. |
|
|
@@ -340,9 +332,9 @@ The in-memory lookup seam. `createAssets` validates a request key before it
|
|
|
340
332
|
calls `read`, copies each successful result, and caches that key for the
|
|
341
333
|
factory's lifetime. A miss may be read again later.
|
|
342
334
|
|
|
343
|
-
| Method | Returns
|
|
344
|
-
| ------ |
|
|
345
|
-
| `read` | `
|
|
335
|
+
| Method | Returns | Summary |
|
|
336
|
+
| ------ | ---------------------------------- | ------------------------------------------------------------------------------- |
|
|
337
|
+
| `read` | `AssetRepresentation \| undefined` | Reads one identity or Brotli asset representation for a validated relative key. |
|
|
346
338
|
|
|
347
339
|
#### `SessionInterface`
|
|
348
340
|
|
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. |
|
|
@@ -72,8 +72,6 @@ Pass `tools` (a non-empty `ToolDefinition[]` from `@orkestrel/tool`) to advertis
|
|
|
72
72
|
|
|
73
73
|
### Surface
|
|
74
74
|
|
|
75
|
-
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 `\|`. An extended interface's name comes before `plus`, with the members it adds after. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none. A `Shape` cell holds the constant's declared type.
|
|
76
|
-
|
|
77
75
|
| Name | Kind | Signature | Summary |
|
|
78
76
|
| -------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
77
|
| `createOllama` | function | `(options: OllamaOptions) => ProviderInterface` | Creates a local Ollama inference provider — a `ProviderInterface` over the daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `stream`. |
|
|
@@ -173,7 +171,7 @@ The session composes the following validators and protocol helpers, each exporte
|
|
|
173
171
|
| `readOllamaBody` | function | `(response: Response, limit: number) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Reads a bounded response and preserves its partial bytes on a transport refusal. |
|
|
174
172
|
| `readOllamaReply` | function | `(origin: string, path: string, options?: OllamaMetadataOptions, signal?: AbortSignal, request?: OllamaBytes, transport?: OllamaDaemonOptions['fetch']) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Exchanges metadata or unload bytes with a dedicated origin under one complete-request deadline. |
|
|
175
173
|
|
|
176
|
-
`OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `
|
|
174
|
+
`OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `DuplexOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
|
|
177
175
|
|
|
178
176
|
## Methods
|
|
179
177
|
|
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`. |
|