@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
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# JSON-RPC 2.0
|
|
2
|
+
|
|
3
|
+
> The JSON-RPC 2.0 wire contract the Orkestrel protocol packages share: the message types, total
|
|
4
|
+
> structural guards that place every parsed JSON value in at most one message arm, the reserved
|
|
5
|
+
> error codes, and the response builders.
|
|
6
|
+
|
|
7
|
+
Source: [`src/core`](../src/core). Published through `@orkestrel/jsonrpc`.
|
|
8
|
+
|
|
9
|
+
## Messages
|
|
10
|
+
|
|
11
|
+
A JSON-RPC 2.0 message is an invocation or a response. An invocation is a `JSONRPCRequest`, which
|
|
12
|
+
carries an `id` and requires a response, or a `JSONRPCNotification`, which carries no `id` member
|
|
13
|
+
and permits none. A response is a `JSONRPCResultResponse`, which echoes the request's `id` beside a
|
|
14
|
+
`result`, or a `JSONRPCErrorResponse`, which carries a `JSONRPCError` under `error`.
|
|
15
|
+
`JSONRPCInvocation`, `JSONRPCResponse`, and `JSONRPCMessage` name the unions.
|
|
16
|
+
|
|
17
|
+
A `JSONRPCId` is a string or a finite integer, and never `null`. An error response always carries an
|
|
18
|
+
`id` member, and the member holds `null` when the request's id could not be read. A request and a
|
|
19
|
+
result response always carry an id.
|
|
20
|
+
|
|
21
|
+
The package carries parameters by name only: a present `params` member is a record, and the guards
|
|
22
|
+
refuse a by-position array.
|
|
23
|
+
|
|
24
|
+
The guards partition every value whose presence checks and member reads agree. An invocation guard
|
|
25
|
+
refuses a value carrying a `result` or `error` member, a response guard refuses a value carrying a
|
|
26
|
+
`method` member, the notification guard refuses any `id` member, the result-response guard refuses
|
|
27
|
+
an `error` member, and the error-response guard refuses a `result` member. A value carrying both an
|
|
28
|
+
invocation's and a response's members is no message. A `Proxy` whose `has` and `get` traps
|
|
29
|
+
disagree can satisfy several arms: a `has` trap that denies every member lets one value pass as a
|
|
30
|
+
notification and as an error response.
|
|
31
|
+
|
|
32
|
+
### Classify a message
|
|
33
|
+
|
|
34
|
+
Pass any parsed value to a guard. Each guard answers for one arm, and `isJSONRPCMessage` answers
|
|
35
|
+
for all of them:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { isJSONRPCInvocation, isJSONRPCMessage, isJSONRPCResponse } from '@orkestrel/jsonrpc'
|
|
39
|
+
|
|
40
|
+
const hybrid: unknown = JSON.parse('{"jsonrpc":"2.0","id":1,"method":"ping","result":null}')
|
|
41
|
+
|
|
42
|
+
isJSONRPCMessage(hybrid) // false
|
|
43
|
+
isJSONRPCInvocation({ jsonrpc: '2.0', method: 'initialized' }) // true
|
|
44
|
+
isJSONRPCResponse({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) // true
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Responses
|
|
48
|
+
|
|
49
|
+
`buildJSONRPCResult` echoes a request's id beside a result. The id must be an integer or a string
|
|
50
|
+
and the result a JSON value, and the builder checks neither. `buildJSONRPCError` writes the
|
|
51
|
+
id it is given, `null` included, and omits `data` from the error object when the argument is
|
|
52
|
+
absent. The five `JSONRPC_*` constants are the codes JSON-RPC 2.0 reserves for a parse failure, an
|
|
53
|
+
invalid request, an unknown method, invalid parameters, and an internal failure. The package throws
|
|
54
|
+
no error of its own.
|
|
55
|
+
|
|
56
|
+
### Answer a request
|
|
57
|
+
|
|
58
|
+
Parse the payload, answer an unreadable or invalid request with `id: null`, and echo the id of every
|
|
59
|
+
request the guard accepts:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import type { JSONRPCResponse } from '@orkestrel/jsonrpc'
|
|
63
|
+
import {
|
|
64
|
+
buildJSONRPCError,
|
|
65
|
+
buildJSONRPCResult,
|
|
66
|
+
isJSONRPCRequest,
|
|
67
|
+
JSONRPC_INVALID_REQUEST,
|
|
68
|
+
JSONRPC_METHOD_NOT_FOUND,
|
|
69
|
+
JSONRPC_PARSE_ERROR,
|
|
70
|
+
} from '@orkestrel/jsonrpc'
|
|
71
|
+
|
|
72
|
+
function answer(text: string): JSONRPCResponse {
|
|
73
|
+
let value: unknown
|
|
74
|
+
try {
|
|
75
|
+
value = JSON.parse(text)
|
|
76
|
+
} catch {
|
|
77
|
+
return buildJSONRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error')
|
|
78
|
+
}
|
|
79
|
+
if (!isJSONRPCRequest(value)) {
|
|
80
|
+
return buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Invalid Request')
|
|
81
|
+
}
|
|
82
|
+
if (value.method !== 'ping') {
|
|
83
|
+
return buildJSONRPCError(value.id, JSONRPC_METHOD_NOT_FOUND, 'Method not found')
|
|
84
|
+
}
|
|
85
|
+
return buildJSONRPCResult(value.id, 'pong')
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
answer('{') // { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }
|
|
89
|
+
answer('{"jsonrpc":"2.0","id":7,"method":"ping"}') // { jsonrpc: '2.0', id: 7, result: 'pong' }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Validation
|
|
93
|
+
|
|
94
|
+
Every guard takes `unknown` and never throws. `isJSONRPCId` accepts a string or a finite integer,
|
|
95
|
+
and every other guard returns `false` for a value that is not a plain record. A guard reads members
|
|
96
|
+
through property access, so an accessor or a `Proxy` with no traps passes when the members it
|
|
97
|
+
yields pass. A member that throws on read fails the value, except a `data` member and a member the
|
|
98
|
+
contract does not name: no guard reads either, so a throwing accessor there passes. A guard accepts
|
|
99
|
+
members the contract does not name.
|
|
100
|
+
|
|
101
|
+
- `isJSONRPCId` accepts a string, the empty string included, and a finite integer.
|
|
102
|
+
- `isJSONRPCError` requires an integer `code` and a string `message`, and accepts any `data`.
|
|
103
|
+
- `isJSONRPCRequest` requires `jsonrpc: '2.0'`, an id, and a string `method`.
|
|
104
|
+
- `isJSONRPCNotification` requires `jsonrpc: '2.0'` and a string `method`, and refuses an `id`
|
|
105
|
+
member whatever it holds, `undefined` and `null` included.
|
|
106
|
+
- `isJSONRPCResultResponse` requires `jsonrpc: '2.0'`, an id, and a `result` member holding any
|
|
107
|
+
value but `undefined`, which JSON cannot carry.
|
|
108
|
+
- `isJSONRPCErrorResponse` requires `jsonrpc: '2.0'`, an `id` member holding an id or `null`, and
|
|
109
|
+
an `error` that `isJSONRPCError` accepts.
|
|
110
|
+
- `isJSONRPCInvocation`, `isJSONRPCResponse`, and `isJSONRPCMessage` accept what their arms accept.
|
|
111
|
+
|
|
112
|
+
The following calls show each boundary:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import {
|
|
116
|
+
isJSONRPCError,
|
|
117
|
+
isJSONRPCErrorResponse,
|
|
118
|
+
isJSONRPCId,
|
|
119
|
+
isJSONRPCNotification,
|
|
120
|
+
isJSONRPCResultResponse,
|
|
121
|
+
} from '@orkestrel/jsonrpc'
|
|
122
|
+
|
|
123
|
+
isJSONRPCId(1.5) // false
|
|
124
|
+
isJSONRPCError({ code: -32601, message: 'Method not found', data: { method: 'ping' } }) // true
|
|
125
|
+
isJSONRPCNotification({ jsonrpc: '2.0', method: 'log', id: undefined }) // false
|
|
126
|
+
isJSONRPCResultResponse({ jsonrpc: '2.0', id: 1, result: null }) // true
|
|
127
|
+
isJSONRPCErrorResponse({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' } }) // false
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Surface
|
|
131
|
+
|
|
132
|
+
### Message types
|
|
133
|
+
|
|
134
|
+
The package provides these message contracts.
|
|
135
|
+
|
|
136
|
+
| Name | Kind | Signature | Summary |
|
|
137
|
+
| ----------------------- | --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
138
|
+
| `JSONRPCId` | type | `string \| number` | Identifies a JSON-RPC 2.0 request and the response that answers it. |
|
|
139
|
+
| `JSONRPCRequest` | interface | `{ jsonrpc, id, method, params? }` | Describes a JSON-RPC 2.0 method call that requires a response. |
|
|
140
|
+
| `JSONRPCNotification` | interface | `{ jsonrpc, method, id?, params? }` | Describes a JSON-RPC 2.0 method call that permits no response. |
|
|
141
|
+
| `JSONRPCInvocation` | type | `JSONRPCRequest \| JSONRPCNotification` | Describes one inbound JSON-RPC 2.0 call, a request or a notification. |
|
|
142
|
+
| `JSONRPCError` | interface | `{ code, message, data? }` | Describes the error object a JSON-RPC 2.0 error response carries. |
|
|
143
|
+
| `JSONRPCResultResponse` | interface | `{ jsonrpc, id, result, error? }` | Describes a successful JSON-RPC 2.0 response. |
|
|
144
|
+
| `JSONRPCErrorResponse` | interface | `{ jsonrpc, id, error, result? }` | Describes a failed JSON-RPC 2.0 response, with `id` set to `null` when the request's id could not be read. |
|
|
145
|
+
| `JSONRPCResponse` | type | `JSONRPCResultResponse \| JSONRPCErrorResponse` | Describes either outcome of a JSON-RPC 2.0 request. |
|
|
146
|
+
| `JSONRPCMessage` | type | `JSONRPCInvocation \| JSONRPCResponse` | Describes one complete JSON-RPC 2.0 wire message. |
|
|
147
|
+
|
|
148
|
+
### Error codes
|
|
149
|
+
|
|
150
|
+
The package provides these reserved error codes.
|
|
151
|
+
|
|
152
|
+
| Name | Kind | Signature | Summary |
|
|
153
|
+
| -------------------------- | ----- | --------- | ------------------------------------------------------------------------ |
|
|
154
|
+
| `JSONRPC_PARSE_ERROR` | const | `-32700` | Identifies a payload that is not valid JSON, `-32700`. |
|
|
155
|
+
| `JSONRPC_INVALID_REQUEST` | const | `-32600` | Identifies a payload that is not a valid JSON-RPC 2.0 request, `-32600`. |
|
|
156
|
+
| `JSONRPC_METHOD_NOT_FOUND` | const | `-32601` | Identifies a method the receiver does not provide, `-32601`. |
|
|
157
|
+
| `JSONRPC_INVALID_PARAMS` | const | `-32602` | Identifies invalid method parameters, `-32602`. |
|
|
158
|
+
| `JSONRPC_INTERNAL_ERROR` | const | `-32603` | Identifies an internal receiver failure, `-32603`. |
|
|
159
|
+
|
|
160
|
+
### Guards
|
|
161
|
+
|
|
162
|
+
The package provides these guards.
|
|
163
|
+
|
|
164
|
+
| Name | Kind | Signature | Summary |
|
|
165
|
+
| ------------------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
166
|
+
| `isJSONRPCId` | function | `(value: unknown) => value is JSONRPCId` | Checks whether a value is a JSON-RPC 2.0 id, a string or a finite integer. |
|
|
167
|
+
| `isJSONRPCError` | function | `(value: unknown) => value is JSONRPCError` | Checks whether a value is a JSON-RPC 2.0 error object. |
|
|
168
|
+
| `isJSONRPCRequest` | function | `(value: unknown) => value is JSONRPCRequest` | Checks whether a value is a JSON-RPC 2.0 request. |
|
|
169
|
+
| `isJSONRPCNotification` | function | `(value: unknown) => value is JSONRPCNotification` | Checks whether a value is a JSON-RPC 2.0 notification. |
|
|
170
|
+
| `isJSONRPCInvocation` | function | `(value: unknown) => value is JSONRPCInvocation` | Checks whether a value is a JSON-RPC 2.0 request or notification. |
|
|
171
|
+
| `isJSONRPCResultResponse` | function | `(value: unknown) => value is JSONRPCResultResponse` | Checks whether a value is a successful JSON-RPC 2.0 response. |
|
|
172
|
+
| `isJSONRPCErrorResponse` | function | `(value: unknown) => value is JSONRPCErrorResponse` | Checks whether a value is a failed JSON-RPC 2.0 response. |
|
|
173
|
+
| `isJSONRPCResponse` | function | `(value: unknown) => value is JSONRPCResponse` | Checks whether a value is a JSON-RPC 2.0 response. |
|
|
174
|
+
| `isJSONRPCMessage` | function | `(value: unknown) => value is JSONRPCMessage` | Checks whether a value is a JSON-RPC 2.0 message. |
|
|
175
|
+
|
|
176
|
+
### Builders
|
|
177
|
+
|
|
178
|
+
The package provides these response builders.
|
|
179
|
+
|
|
180
|
+
| Name | Kind | Signature | Summary |
|
|
181
|
+
| -------------------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
|
|
182
|
+
| `buildJSONRPCResult` | function | `(id: JSONRPCId, result: unknown) => JSONRPCResultResponse` | Builds a successful JSON-RPC 2.0 response that echoes the request's id. |
|
|
183
|
+
| `buildJSONRPCError` | function | `(id: JSONRPCId \| null, code: number, message: string, data?: unknown) => JSONRPCErrorResponse` | Builds a failed JSON-RPC 2.0 response, omitting `data` when it is absent. |
|
|
184
|
+
|
|
185
|
+
## Tests
|
|
186
|
+
|
|
187
|
+
[`tests/src/core`](../tests/src/core) proves the guards, the builders, and the barrel.
|
package/dist/host/guides/lsp.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Language Server Protocol client
|
|
2
2
|
|
|
3
3
|
> A typed Language Server Protocol client over an injected byte transport: a host-independent core
|
|
4
|
-
> carrying the base-protocol framing codec, the
|
|
4
|
+
> carrying the base-protocol framing codec, the protocol guards, and an `LSPClient`
|
|
5
5
|
> that completes the initialize handshake, owns opened document URIs, and selects pull or push
|
|
6
6
|
> diagnostics from the server's own capabilities, beside a server environment whose
|
|
7
|
-
> `
|
|
7
|
+
> `LSPStdioTransport` carries those bytes over a language server run as a child process.
|
|
8
8
|
|
|
9
9
|
Source: [`src/core`](../src/core) and [`src/server`](../src/server). Published through
|
|
10
10
|
`@orkestrel/lsp` and `@orkestrel/lsp/server`.
|
|
@@ -91,7 +91,8 @@ obligation.
|
|
|
91
91
|
Drive that seam directly to carry one frame without a client:
|
|
92
92
|
|
|
93
93
|
```ts
|
|
94
|
-
import type { JSONRPCNotification
|
|
94
|
+
import type { JSONRPCNotification } from '@orkestrel/jsonrpc'
|
|
95
|
+
import type { LSPTransportInterface } from '@orkestrel/lsp'
|
|
95
96
|
import { encodeLSPMessage } from '@orkestrel/lsp'
|
|
96
97
|
|
|
97
98
|
declare const transport: LSPTransportInterface
|
|
@@ -113,7 +114,7 @@ before the client destroys its emitter. At the deadline, the client emits an `LS
|
|
|
113
114
|
|
|
114
115
|
## Stdio client transport
|
|
115
116
|
|
|
116
|
-
The server environment publishes `
|
|
117
|
+
The server environment publishes `LSPStdioTransport`, the byte transport over a language server run as
|
|
117
118
|
a child process. It carries bytes and never frames: every standard-output chunk reaches the `chunk`
|
|
118
119
|
event exactly as the host delivered it, so a frame split across reads and two frames coalesced into
|
|
119
120
|
one read both arrive unaltered and the client's parser owns the framing. Standard error is read
|
|
@@ -133,12 +134,12 @@ Spawn a language server as a child process and drive it through the stdio transp
|
|
|
133
134
|
|
|
134
135
|
```ts
|
|
135
136
|
import { createLSPClient } from '@orkestrel/lsp'
|
|
136
|
-
import {
|
|
137
|
+
import { createLSPStdioTransport } from '@orkestrel/lsp/server'
|
|
137
138
|
import { pathToFileURL } from 'node:url'
|
|
138
139
|
|
|
139
140
|
declare const directory: string
|
|
140
141
|
|
|
141
|
-
const transport =
|
|
142
|
+
const transport = createLSPStdioTransport({
|
|
142
143
|
server: { command: ['my-language-server', '--stdio'], directory },
|
|
143
144
|
grace: 5_000,
|
|
144
145
|
})
|
|
@@ -150,7 +151,7 @@ await client.destroy()
|
|
|
150
151
|
`grace` bounds the cooperative termination window in milliseconds, and `5000` applies when it is
|
|
151
152
|
absent. `close()` closes the child's input channel, waits `grace` for that closure's flush and the
|
|
152
153
|
child's own ending together on one shared deadline rather than a window for each, and hands a child
|
|
153
|
-
that outlives that window to the process package
|
|
154
|
+
that outlives that window to the process package duplex's `stop`, which signals the
|
|
154
155
|
child's process group and escalates to an unconditional kill after `grace` again. The child leads
|
|
155
156
|
its own process group on a POSIX host, so that signal reaches its whole tree; Windows carries no
|
|
156
157
|
such group, so the host's `taskkill` utility ends the tree there instead. `close()` then waits up to
|
|
@@ -247,7 +248,9 @@ if (boundary !== undefined) {
|
|
|
247
248
|
## Validation
|
|
248
249
|
|
|
249
250
|
Every payload this package reads off the wire arrives as `unknown`, so each guard narrows one
|
|
250
|
-
shape and returns `false` for anything else.
|
|
251
|
+
shape and returns `false` for anything else. The JSON-RPC 2.0 envelope types, guards, and error
|
|
252
|
+
codes the codec and the client read come from `@orkestrel/jsonrpc`, so narrow a decoded frame by
|
|
253
|
+
its JSON-RPC role through that package:
|
|
251
254
|
|
|
252
255
|
```ts
|
|
253
256
|
import {
|
|
@@ -255,7 +258,7 @@ import {
|
|
|
255
258
|
isJSONRPCNotification,
|
|
256
259
|
isJSONRPCRequest,
|
|
257
260
|
isJSONRPCResponse,
|
|
258
|
-
} from '@orkestrel/
|
|
261
|
+
} from '@orkestrel/jsonrpc'
|
|
259
262
|
|
|
260
263
|
declare const message: unknown
|
|
261
264
|
declare const payload: unknown
|
|
@@ -376,21 +379,17 @@ const first = chain.next()
|
|
|
376
379
|
|
|
377
380
|
The server surface provides these exports.
|
|
378
381
|
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
|
382
|
-
|
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
385
|
-
| `StdioClientTransportInterface` | interface | `{ pid }` | Defines the stdio transport's own surface beyond the byte transport it carries. |
|
|
386
|
-
| `StdioClientTransportOptions` | interface | `{ on?, error?, server, grace? }` | Configures a Language Server Protocol child process reached over its standard streams. |
|
|
382
|
+
| Name | Kind | Signature | Summary |
|
|
383
|
+
| ---------------------------- | --------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
384
|
+
| `LSPStdioTransport` | class | `new (options: LSPStdioTransportOptions) => LSPStdioTransportInterface` | Streams Language Server Protocol bytes between a client and a child process over stdio. |
|
|
385
|
+
| `createLSPStdioTransport` | function | `(options: LSPStdioTransportOptions) => LSPStdioTransportInterface` | Creates a byte transport over a Language Server Protocol child process. |
|
|
386
|
+
| `LSPStdioTransportInterface` | interface | `{ pid }` | Defines the stdio transport's own surface beyond the byte transport it carries. |
|
|
387
|
+
| `LSPStdioTransportOptions` | interface | `{ on?, error?, server, grace? }` | Configures a Language Server Protocol child process reached over its standard streams. |
|
|
387
388
|
|
|
388
389
|
### Client and transport contracts
|
|
389
390
|
|
|
390
391
|
The client surface provides these entities and configuration contracts.
|
|
391
392
|
|
|
392
|
-
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 `\|`. 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.
|
|
393
|
-
|
|
394
393
|
| Name | Kind | Signature | Summary |
|
|
395
394
|
| ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
396
395
|
| `LSPClient` | class | `new (options: LSPClientOptions) => LSPClientInterface` | Drives a Language Server Protocol peer through an injected byte transport. |
|
|
@@ -414,8 +413,6 @@ The framing, timing, and error surface provides these exports.
|
|
|
414
413
|
It checks the declared code and context members; context objects and callable contexts are accepted
|
|
415
414
|
when their members conform, and message arrays are checked by index without running their iterator.
|
|
416
415
|
|
|
417
|
-
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 `\|`. 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.
|
|
418
|
-
|
|
419
416
|
| Name | Kind | Signature | Summary |
|
|
420
417
|
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
421
418
|
| `encodeLSPMessage` | function | `(message: JSONRPCMessage) => Uint8Array` | Encodes a JSON-RPC message as one byte-accurate LSP base-protocol frame. |
|
|
@@ -433,22 +430,13 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
433
430
|
| `LSPErrorContext` | interface | `{ code?, messages?, value? }` | Describes structured details attached to an `LSPError`. |
|
|
434
431
|
| `LSPErrorOptions` | interface | `{ code, context?, cause? }` | Configures an `LSPError` instance. |
|
|
435
432
|
|
|
436
|
-
###
|
|
433
|
+
### Initialization
|
|
437
434
|
|
|
438
|
-
The
|
|
439
|
-
|
|
440
|
-
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 `\|`.
|
|
435
|
+
The initialization surface provides these payload types. `@orkestrel/jsonrpc` provides the
|
|
436
|
+
JSON-RPC 2.0 envelope types.
|
|
441
437
|
|
|
442
438
|
| Name | Kind | Signature | Summary |
|
|
443
439
|
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
444
|
-
| `JSONRPCId` | type | `string \| number` | Identifies a JSON-RPC request and its matching response. |
|
|
445
|
-
| `JSONRPCRequest` | interface | `{ jsonrpc, id, method, params? }` | Describes a JSON-RPC 2.0 method call that requires a response. |
|
|
446
|
-
| `JSONRPCNotification` | interface | `{ jsonrpc, method, id?, params? }` | Describes a JSON-RPC 2.0 method call that permits no response. |
|
|
447
|
-
| `JSONRPCError` | interface | `{ code, message, data? }` | Describes the error payload carried by a JSON-RPC error response. |
|
|
448
|
-
| `JSONRPCResultResponse` | interface | `{ jsonrpc, id, result, error? }` | Describes a successful JSON-RPC 2.0 response. |
|
|
449
|
-
| `JSONRPCErrorResponse` | interface | `{ jsonrpc, id, error, result? }` | Describes a failed JSON-RPC 2.0 response. |
|
|
450
|
-
| `JSONRPCResponse` | type | `JSONRPCResultResponse \| JSONRPCErrorResponse` | Describes either outcome of a JSON-RPC 2.0 request. |
|
|
451
|
-
| `JSONRPCMessage` | type | `JSONRPCRequest \| JSONRPCNotification \| JSONRPCResponse` | Describes one complete JSON-RPC 2.0 wire message. |
|
|
452
440
|
| `LSPIdentity` | interface | `{ name, version? }` | Describes the name and optional version of an LSP peer. |
|
|
453
441
|
| `LSPInitializeParams` | interface | `{ processId, clientInfo?, rootUri, capabilities }` | Describes the initialization members sent by this client. |
|
|
454
442
|
| `LSPInitializeResult` | interface | `{ capabilities, serverInfo? }` | Describes the successful result of an initialize request. |
|
|
@@ -459,8 +447,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
459
447
|
|
|
460
448
|
The document and diagnostic surface provides these payload types.
|
|
461
449
|
|
|
462
|
-
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 `\|`.
|
|
463
|
-
|
|
464
450
|
| Name | Kind | Signature | Summary |
|
|
465
451
|
| ----------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
466
452
|
| `LSPDocumentURI` | type | `string` | Identifies a document by its Language Server Protocol URI. |
|
|
@@ -485,16 +471,11 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
485
471
|
|
|
486
472
|
### Guards
|
|
487
473
|
|
|
488
|
-
The validation surface provides these guards.
|
|
489
|
-
|
|
490
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
474
|
+
The validation surface provides these guards. `@orkestrel/jsonrpc` provides the JSON-RPC 2.0
|
|
475
|
+
envelope guards.
|
|
491
476
|
|
|
492
477
|
| Name | Kind | Signature | Summary |
|
|
493
478
|
| ------------------------------- | -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
494
|
-
| `isJSONRPCError` | function | `(value: unknown) => value is JSONRPCError` | Checks whether an unknown value is a JSON-RPC error payload. |
|
|
495
|
-
| `isJSONRPCRequest` | function | `(value: unknown) => value is JSONRPCRequest` | Checks whether an unknown value is a JSON-RPC request. |
|
|
496
|
-
| `isJSONRPCNotification` | function | `(value: unknown) => value is JSONRPCNotification` | Checks whether an unknown value is a JSON-RPC notification. |
|
|
497
|
-
| `isJSONRPCResponse` | function | `(value: unknown) => value is JSONRPCResponse` | Checks whether an unknown value is a JSON-RPC response. |
|
|
498
479
|
| `isLSPPosition` | function | `(value: unknown) => value is LSPPosition` | Checks whether an unknown value is an LSP position. |
|
|
499
480
|
| `isLSPRange` | function | `(value: unknown) => value is LSPRange` | Checks whether an unknown value is an LSP range. |
|
|
500
481
|
| `isLSPLocation` | function | `(value: unknown) => value is LSPLocation` | Checks whether an unknown value is an LSP location. |
|
|
@@ -515,8 +496,7 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
|
515
496
|
### Constants
|
|
516
497
|
|
|
517
498
|
The constant surface provides these protocol names, advertisements, and limits.
|
|
518
|
-
|
|
519
|
-
A `Shape` cell holds the constant's declared type.
|
|
499
|
+
`@orkestrel/jsonrpc` provides the JSON-RPC 2.0 error codes, and this table lists the LSP-specific ones.
|
|
520
500
|
|
|
521
501
|
| Name | Kind | Signature | Summary |
|
|
522
502
|
| --------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
@@ -528,11 +508,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
528
508
|
| `LSP_SYNC_KINDS` | const | `readonly [0, 1, 2]` | Lists the text synchronization modes named by the Language Server Protocol. |
|
|
529
509
|
| `LSP_CAPABILITIES` | const | `Readonly<{ general: Readonly<{ positionEncodings: readonly string[]; }>; textDocument: Readonly<{ synchronization: Readonly<{}>; publishDiagnostics: Readonly<{}>; diagnostic: Readonly<{}>; }>; }>` | Describes the capabilities this client advertises in its initialize request. |
|
|
530
510
|
| `LSP_TIMEOUT` | const | `30000` | Names the default request-settlement timeout, `30_000` milliseconds. |
|
|
531
|
-
| `JSONRPC_PARSE_ERROR` | const | `-32700` | Identifies a malformed JSON payload, `-32700`. |
|
|
532
|
-
| `JSONRPC_INVALID_REQUEST` | const | `-32600` | Identifies a structurally invalid JSON-RPC request, `-32600`. |
|
|
533
|
-
| `JSONRPC_METHOD_NOT_FOUND` | const | `-32601` | Identifies a JSON-RPC method that the receiver does not provide, `-32601`. |
|
|
534
|
-
| `JSONRPC_INVALID_PARAMS` | const | `-32602` | Identifies invalid parameters supplied to a JSON-RPC method, `-32602`. |
|
|
535
|
-
| `JSONRPC_INTERNAL_ERROR` | const | `-32603` | Identifies an internal JSON-RPC receiver failure, `-32603`. |
|
|
536
511
|
| `LSP_REQUEST_CANCELLED` | const | `-32800` | Identifies a Language Server Protocol request cancelled by the client, `-32800`. |
|
|
537
512
|
| `LSP_CONTENT_MODIFIED` | const | `-32801` | Identifies a request invalidated by modified document content, `-32801`. |
|
|
538
513
|
| `LSP_SERVER_CANCELLED` | const | `-32802` | Identifies a Language Server Protocol request cancelled by the server, `-32802`. |
|
|
@@ -550,7 +525,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
550
525
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `encodeLSPMessage`, the `scanLSPBoundary` index, the `readLSPHeader` and `readLSPBody` grammars with their coded refusals, and `waitForDeadline`.
|
|
551
526
|
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseLSPMessages` over split, coalesced, and malformed frames, and the state it retains between calls.
|
|
552
527
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard accepts its own shape, refuses a near miss, and stays total for a hostile value.
|
|
553
|
-
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) — `
|
|
554
|
-
- [`tests/src/server/transports/
|
|
528
|
+
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) — `createLSPStdioTransport` returns a working `LSPStdioTransportInterface` over the options it is handed.
|
|
529
|
+
- [`tests/src/server/transports/LSPStdioTransport.test.ts`](../tests/src/server/transports/LSPStdioTransport.test.ts) — spawning, byte carriage into the child and out of it, generation ownership and reconnection, `pid`, and the bounded termination window against a child whose grandchild holds its standard output.
|
|
555
530
|
- [`tests/integration.test.ts`](../tests/integration.test.ts) — the core client driving a real language server child through the stdio transport.
|
|
556
531
|
- [`tests/conformance.test.ts`](../tests/conformance.test.ts) — the subset of Language Server Protocol 3.18 this package speaks, read against the mirrored metaModel instance.
|