@orkestrel/scaffold 0.0.120 → 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.
Files changed (40) hide show
  1. package/dist/bin/main.js +5 -5
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/claude/agents/orkestrel.md +26 -26
  4. package/dist/host/guides/agent.md +5 -5
  5. package/dist/host/guides/brief.md +7 -15
  6. package/dist/host/guides/browser.md +1 -1
  7. package/dist/host/guides/capture.md +2 -2
  8. package/dist/host/guides/console.md +4 -30
  9. package/dist/host/guides/guide.md +0 -1
  10. package/dist/host/guides/interpret.md +165 -182
  11. package/dist/host/guides/lsp.md +26 -51
  12. package/dist/host/guides/mcp.md +220 -276
  13. package/dist/host/guides/middleware.md +14 -22
  14. package/dist/host/guides/ollama.md +1 -3
  15. package/dist/host/guides/probe.md +71 -80
  16. package/dist/host/guides/program.md +26 -35
  17. package/dist/host/guides/qualifier.md +0 -6
  18. package/dist/host/guides/queue.md +0 -4
  19. package/dist/host/guides/rater.md +6 -12
  20. package/dist/host/guides/relation.md +0 -2
  21. package/dist/host/guides/scaffold.md +12 -8
  22. package/dist/host/guides/sea.md +47 -51
  23. package/dist/host/guides/server.md +15 -19
  24. package/dist/host/guides/terminal.md +0 -26
  25. package/dist/host/guides/toolbox.md +0 -10
  26. package/dist/host/guides/worker.md +57 -57
  27. package/dist/host/guides/workflow.md +13 -26
  28. package/dist/host/guides/workspace.md +15 -21
  29. package/dist/host/manifest.json +28 -448
  30. package/dist/src/core/index.cjs +7 -45
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.js +7 -45
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +10 -9
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +12 -8
  37. package/dist/src/server/index.d.ts +12 -8
  38. package/dist/src/server/index.js +10 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +5 -5
@@ -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 JSON-RPC and protocol guards, and an `LSPClient`
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
- > `StdioClientTransport` carries those bytes over a language server run as a child process.
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, LSPTransportInterface } from '@orkestrel/lsp'
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 `StdioClientTransport`, the byte transport over a language server run as
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 { createStdioClientTransport } from '@orkestrel/lsp/server'
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 = createStdioClientTransport({
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 session's `stop`, which signals the
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. Narrow a decoded frame by its JSON-RPC role:
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/lsp'
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
- 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.
380
-
381
- | Name | Kind | Signature | Summary |
382
- | ------------------------------- | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
383
- | `StdioClientTransport` | class | `new (options: StdioClientTransportOptions) => StdioClientTransportInterface` | Streams Language Server Protocol bytes between a client and a child process over stdio. |
384
- | `createStdioClientTransport` | function | `(options: StdioClientTransportOptions) => StdioClientTransportInterface` | Creates a byte transport over a Language Server Protocol child process. |
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
- ### JSON-RPC and initialization
433
+ ### Initialization
437
434
 
438
- The JSON-RPC and initialization surface provides these payload types.
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) — `createStdioClientTransport` returns a working `StdioClientTransportInterface` over the options it is handed.
554
- - [`tests/src/server/transports/StdioClientTransport.test.ts`](../tests/src/server/transports/StdioClientTransport.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.
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.