@effected/lsp 0.0.0-stage → 0.1.0

package/LspProcess.js

@@ -0,0 +1,282 @@
+import { LspFrame, LspFrameError } from "./LspFrame.js";
+import { LspTestFailure } from "./LspTestFailure.js";
+import { isLspMessage, notJsonRpc, truncate } from "./internal/messages.js";
+import { Cause, Deferred, Duration, Effect, Option, Queue, Ref, Result, Stream, SubscriptionRef } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+
+//#region src/LspProcess.ts
+const concat = (chunks) => {
+	const bytes = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
+	let at = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, at);
+		at += chunk.length;
+	}
+	return bytes;
+};
+/**
+* A spawned Language Server bin a test writes `Content-Length` frames to
+* while it runs — the LSP twin of `@effected/mcp/testing`'s `McpProcess`.
+*
+* @remarks
+* Build the command in the test file with `execPath` and an explicit `env`:
+* `ChildProcess.make(process.execPath, [bin, "--stdio"], { env })`. The child
+* lives for the scope `spawn` runs in, and is killed when it closes.
+*
+* - `nextMessage` fails `StreamEnded` once stdout ends — a stream that ends
+*   inside a frame included — so a child that exits early fails the test
+*   instead of hanging it. Bytes that are not a frame fail `InvalidFrame`; a
+*   frame whose body is not a JSON-RPC 2.0 message fails `NotJsonRpc`.
+* - `send` writes one frame with `LspFrame.encode` from the main entry, so `Content-Length`
+*   counts bytes; `sendRaw` writes a string or bytes exactly as given, for a
+*   malformed frame or one frame split across writes.
+* - `readUntilResponse` reads past notifications and server requests to the
+*   response with the matching id, and returns what it saw.
+* - `closeStdin` is `Queue.end`, so every frame already sent is delivered
+*   before stdin closes. The specification makes a server exit on the `exit`
+*   notification with stdin still open; close stdin only to test a client
+*   disconnect.
+* - Every stdout byte is kept, apart from the decoder: `stdoutSoFar` and
+*   `stdoutFinal` return it raw, and `assertOnlyFrames` proves it held
+*   nothing but well-formed frames, even after the decoder has failed.
+*
+* @example
+* ```ts
+* import { LspProcess } from "@effected/lsp/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const server = yield* LspProcess.spawn(ChildProcess.make(process.execPath, ["./bin/lsp.js", "--stdio"]));
+* 	yield* server.send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { processId: null, rootUri: null, capabilities: {} } });
+* 	const { response } = yield* server.readUntilResponse(1);
+* 	yield* server.send({ jsonrpc: "2.0", method: "initialized", params: {} });
+* 	yield* server.send({ jsonrpc: "2.0", id: 2, method: "shutdown" });
+* 	yield* server.readUntilResponse(2);
+* 	yield* server.send({ jsonrpc: "2.0", method: "exit" });
+* 	const exitCode = yield* server.exitCode;
+* 	// Stdout carried nothing but frames: no stray log line before, between or after them.
+* 	yield* server.assertOnlyFrames;
+* 	return { response, exitCode };
+* }).pipe(Effect.scoped);
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
+* @public
+*/
+var LspProcess = class LspProcess {
+	/**
+	* Write one message to the child's stdin as a `Content-Length` frame.
+	*
+	* @remarks
+	* Never fails. A frame sent after `closeStdin` is dropped, and a write the
+	* child can no longer receive fails the stdin pump instead; the next
+	* `StreamEnded` message names that failure.
+	*/
+	send;
+	/**
+	* Write `bytes` to the child's stdin exactly as given: a string as UTF-8,
+	* bytes unchanged, with no framing added.
+	*
+	* @remarks
+	* For frames `send` cannot produce: a header without `Content-Length`, a
+	* body that is not JSON, or one frame split across several writes,
+	* including mid-character by passing bytes. Never fails, on the same terms
+	* as `send`.
+	*/
+	sendRaw;
+	/**
+	* The next message on stdout.
+	*
+	* @remarks
+	* Fails `StreamEnded` once stdout ends, including inside a frame;
+	* `InvalidFrame` when stdout carried bytes that are not a frame (a log
+	* line on the wire); `NotJsonRpc` for a well-framed body that is not a
+	* JSON-RPC 2.0 message. A frame failure is final: every later read fails
+	* the same way.
+	*/
+	nextMessage;
+	/** Read messages up to and including the response with this id; `seen` holds every message read, the response last. */
+	readUntilResponse;
+	/** End stdin after every frame already sent. */
+	closeStdin;
+	/** Wait for the child to exit. */
+	exitCode;
+	/** Everything written to stderr so far. */
+	stderrSoFar;
+	/**
+	* Wait until everything written to stderr so far satisfies `predicate`,
+	* and return that text.
+	*
+	* @remarks
+	* Event-driven: the predicate is checked against the current text at once,
+	* then again on every chunk the child writes, never on a polling timer.
+	* Fails `StreamEnded` when stderr ends (the child exited) without the
+	* predicate holding, and `TimedOut` once `options.timeout` passes; both
+	* messages carry the stderr seen so far. Reach for it whenever a report
+	* lands on a later tick than the messages a test reads, such as a crash
+	* guard's report once the server is serving. `options.timeout` is real
+	* time: run the test under `it.live`.
+	*/
+	stderrUntil;
+	/** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
+	stderrFinal;
+	/** Every byte written to stdout so far, undecoded. */
+	stdoutSoFar;
+	/** Every byte written to stdout, once stdout has ended. Waits for the child to exit. */
+	stdoutFinal;
+	/**
+	* Wait for stdout to end, then prove it carried nothing but well-formed
+	* `Content-Length` frames of JSON-RPC 2.0 messages, and return those
+	* messages.
+	*
+	* @remarks
+	* The stdout hygiene check: a stray byte before the first frame, between
+	* two frames or after the last fails `InvalidFrame`, whose message names
+	* the stream offset and quotes the offending bytes; so does a stream that
+	* ends inside a frame. A well-framed body that is not JSON-RPC fails
+	* `NotJsonRpc`. It reads the raw capture, not `nextMessage`'s queue, so
+	* the messages a test already read are still checked. It waits for the
+	* child to exit: send `exit` (or close stdin) first.
+	*/
+	assertOnlyFrames;
+	constructor(parts) {
+		this.send = parts.send;
+		this.sendRaw = parts.sendRaw;
+		this.nextMessage = parts.nextMessage;
+		this.readUntilResponse = parts.readUntilResponse;
+		this.closeStdin = parts.closeStdin;
+		this.exitCode = parts.exitCode;
+		this.stderrSoFar = parts.stderrSoFar;
+		this.stderrUntil = parts.stderrUntil;
+		this.stderrFinal = parts.stderrFinal;
+		this.stdoutSoFar = parts.stdoutSoFar;
+		this.stdoutFinal = parts.stdoutFinal;
+		this.assertOnlyFrames = parts.assertOnlyFrames;
+	}
+	/** Spawn `command` for the life of the current scope. */
+	static spawn = (command) => Effect.map(spawnParts(command), (parts) => new LspProcess(parts));
+};
+/**
+* The machinery behind {@link LspProcess.spawn}, shared with `LspProbe` so
+* there is one stdout reader.
+*
+* @internal
+*/
+const spawnParts = (command, options = {}) => Effect.gen(function* () {
+	const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(command);
+	const encoder = new TextEncoder();
+	const stdin = yield* Queue.unbounded();
+	const pumpFailure = yield* Ref.make(void 0);
+	yield* Stream.run(Stream.fromQueue(stdin), handle.stdin).pipe(Effect.catch((error) => Ref.set(pumpFailure, error.message)), Effect.forkScoped);
+	const raw = [];
+	const stdoutDone = yield* Deferred.make();
+	const chunks = yield* Queue.unbounded();
+	yield* handle.stdout.pipe(Stream.runForEach((chunk) => {
+		raw.push(chunk);
+		return Effect.asVoid(Queue.offer(chunks, chunk));
+	}), Effect.matchEffect({
+		onFailure: (error) => Queue.fail(chunks, error),
+		onSuccess: () => Queue.end(chunks)
+	}), Effect.ensuring(Deferred.succeed(stdoutDone, void 0)), Effect.forkScoped);
+	const inbox = yield* Queue.unbounded();
+	yield* LspFrame.decodeStream(Stream.fromQueue(chunks)).pipe(Stream.runForEach((message) => Effect.asVoid(Queue.offer(inbox, message))), Effect.matchEffect({
+		onFailure: (error) => Queue.fail(inbox, error),
+		onSuccess: () => Queue.end(inbox)
+	}), Effect.forkScoped);
+	const stdoutSoFar = Effect.sync(() => concat(raw));
+	const stdoutFinal = Effect.andThen(Deferred.await(stdoutDone), stdoutSoFar);
+	const stderr = yield* SubscriptionRef.make({
+		text: "",
+		done: false
+	});
+	const stderrDone = yield* Deferred.make();
+	yield* Stream.decodeText(handle.stderr).pipe(Stream.runForEach((text) => SubscriptionRef.update(stderr, (sofar) => ({
+		text: sofar.text + text,
+		done: false
+	}))), Effect.ignore, Effect.ensuring(Effect.andThen(SubscriptionRef.update(stderr, (sofar) => ({
+		text: sofar.text,
+		done: true
+	})), Deferred.succeed(stderrDone, void 0))), Effect.forkScoped);
+	const stderrSoFar = Effect.map(SubscriptionRef.get(stderr), (state) => state.text);
+	const stderrFinal = Effect.andThen(Deferred.await(stderrDone), stderrSoFar);
+	const stderrUntil = (predicate, until) => SubscriptionRef.changes(stderr).pipe(Stream.filter((state) => state.done || predicate(state.text)), Stream.runHead, Effect.flatMap((found) => {
+		const state = Option.getOrElse(found, () => ({
+			text: "",
+			done: true
+		}));
+		return predicate(state.text) ? Effect.succeed(state.text) : Effect.fail(new LspTestFailure({
+			reason: "StreamEnded",
+			message: `the server's stderr ended before it matched; stderr: ${truncate(state.text)}`
+		}));
+	}), Effect.timeoutOrElse({
+		duration: until.timeout,
+		orElse: () => Effect.flatMap(stderrSoFar, (text) => Effect.fail(new LspTestFailure({
+			reason: "TimedOut",
+			message: `the server's stderr did not match within ${Duration.format(Duration.fromInputUnsafe(until.timeout))}; stderr so far: ${truncate(text)}`
+		})))
+	}));
+	const ended = (why) => Effect.gen(function* () {
+		const pending = options.pending === void 0 ? "the expected message" : yield* options.pending;
+		const pump = yield* Ref.get(pumpFailure);
+		const pumpText = pump === void 0 ? "" : `; stdin pump failed: ${truncate(pump)}`;
+		if (options.settle === true) {
+			const code = yield* Effect.match(handle.exitCode, {
+				onFailure: (error) => `unknown (${error.message})`,
+				onSuccess: (exitCode) => String(Number(exitCode))
+			});
+			const text = yield* stderrFinal;
+			return yield* new LspTestFailure({
+				reason: "StreamEnded",
+				message: `the server's stdout ${why} before ${pending}; the server exited with code ${code}; stderr: ${text === "" ? "(empty)" : truncate(text)}${pumpText}`
+			});
+		}
+		const text = yield* stderrSoFar;
+		return yield* new LspTestFailure({
+			reason: "StreamEnded",
+			message: `the server's stdout ${why} before ${pending}; stderr so far: ${text === "" ? "(empty)" : truncate(text)}${pumpText}`
+		});
+	});
+	const nextMessage = Queue.take(inbox).pipe(Effect.catch((error) => Cause.isDone(error) ? ended("ended") : error instanceof LspFrameError ? error.code === "Truncated" ? ended(`ended inside a frame (${error.message})`) : Effect.fail(new LspTestFailure({
+		reason: "InvalidFrame",
+		message: `the server's stdout is not LSP frames: ${error.message}`
+	})) : ended(`failed to read (${error.message})`)), Effect.flatMap((message) => isLspMessage(message) ? Effect.succeed(message) : Effect.fail(notJsonRpc(message))));
+	const readUntilResponse = (id) => Effect.gen(function* () {
+		const seen = [];
+		while (true) {
+			const message = yield* nextMessage;
+			seen.push(message);
+			if (message.method === void 0 && message.id === id) return {
+				response: message,
+				seen
+			};
+		}
+	});
+	const assertOnlyFrames = Effect.flatMap(stdoutFinal, (bytes) => {
+		const decoded = LspFrame.decodeAllResult(bytes);
+		if (Result.isFailure(decoded)) return Effect.fail(new LspTestFailure({
+			reason: "InvalidFrame",
+			message: `the server's stdout carried bytes outside a well-formed frame: ${decoded.failure.message}`
+		}));
+		const stray = decoded.success.find((message) => !isLspMessage(message));
+		return stray === void 0 ? Effect.succeed(decoded.success) : Effect.fail(notJsonRpc(stray));
+	});
+	const sendRaw = (bytes) => Effect.asVoid(Queue.offer(stdin, typeof bytes === "string" ? encoder.encode(bytes) : bytes));
+	return {
+		send: (message) => sendRaw(LspFrame.encode(message)),
+		sendRaw,
+		nextMessage,
+		readUntilResponse,
+		closeStdin: Effect.asVoid(Queue.end(stdin)),
+		exitCode: Effect.map(handle.exitCode, (code) => Number(code)),
+		stderrSoFar,
+		stderrUntil,
+		stderrFinal,
+		stdoutSoFar,
+		stdoutFinal,
+		assertOnlyFrames
+	};
+});
+
+//#endregion
+export { LspProcess, spawnParts };

package/LspStdio.js

@@ -0,0 +1,117 @@
+import { LaunchFailed } from "./internal/LaunchFailed.js";
+import { Cause, Effect, Exit, References, Runtime } from "effect";
+
+//#region src/LspStdio.ts
+/**
+* Run an Effect Language Server over stdio without ever writing a log line or
+* a failure report onto stdout, which is the LSP wire, and exit with the code
+* the LSP specification requires.
+*
+* @remarks
+* The `main.ts`, where `serve` is the server's own program and returns an
+* {@link LspSessionEnd} when its message loop stops:
+*
+* ```ts
+* NodeRuntime.runMain(LspStdio.launch(serve.pipe(Effect.provide(AppLayer))), { teardown: LspStdio.teardown(process) })
+* ```
+*
+* - {@link LspStdio.launch} provides `LogToStderr` to the whole program, and
+*   reports a failure itself, on stderr, hiding it from `runMain`, whose own
+*   report is written outside anything the program can provide. A layer that
+*   fails to build (a missing `HOME`, a bad config) is such a failure.
+* - {@link LspStdio.exitCode} is the specification's rule: `exit` without a
+*   prior `shutdown` exits 1, everything else 0. `launch` applies it to the
+*   program's result.
+* - {@link LspStdio.teardown} keeps that code, maps an interrupt-only exit
+*   (SIGINT, SIGTERM) to 0 instead of 130, and ends the process explicitly:
+*   with stdin still open, as the specification leaves it after `exit`, the
+*   event loop never drains on its own.
+*
+* Never `NodeRuntime.runMain(serve.pipe(Effect.provide(Layer.succeed(References.LogToStderr, true))))`:
+* it typechecks and serves, but a failure is still reported by `runMain`
+* through `console.log`, straight onto the wire, where the client reads it as
+* a malformed frame instead of an error.
+*
+* This is not an LSP framework: the message loop, `initialize` and every
+* request handler stay with whatever the server is built on.
+*
+* @public
+*/
+var LspStdio = class LspStdio {
+	constructor() {}
+	/**
+	* The specification's exit code for a session: 1 when `exit` arrived
+	* without a prior `shutdown`, otherwise 0.
+	*
+	* @remarks
+	* A session whose stdin closed without `exit` (`"closed"`) is a client
+	* disconnect the specification gives no code for; it maps to 0, with or
+	* without `shutdown`.
+	*/
+	static exitCode(end) {
+		return end.reason === "exit" && !end.shutdownReceived ? 1 : 0;
+	}
+	/**
+	* Run `program` with `LogToStderr` set, map its {@link LspSessionEnd} to
+	* an exit code with {@link LspStdio.exitCode}, and report any failure
+	* other than an interrupt on stderr here, re-raising it marked as already
+	* reported and keeping its exit code.
+	*
+	* @remarks
+	* `runMain` logs an unhandled failure from outside the program, where no
+	* `Effect.provide` the program applies reaches, and Effect's default logger
+	* writes through `console.log` unless `LogToStderr` is set. For a Language
+	* Server that is stdout, the wire. `launch` catches the cause inside its
+	* own `LogToStderr` provision, logs it there, and fails with an error
+	* `runMain` does not report again, whose `Runtime.errorExitCode` is the
+	* original failure's (1 unless it carries its own).
+	*
+	* `LogToStderr` reaches every logger that honours it: Effect's default
+	* logger and `Logger.consolePretty`. `Logger.consoleJson`,
+	* `Logger.consoleLogFmt` and `Logger.consoleStructured` write through
+	* `console.log` whatever it says; wrap a formatter in
+	* `Logger.withConsoleError` instead. `Console.log` is not a logger and
+	* still writes to stdout.
+	*
+	* The success value is the exit code; pair `launch` with
+	* {@link LspStdio.teardown}, which hands it to `runMain` and ends the
+	* process with it.
+	*/
+	static launch = (program) => program.pipe(Effect.map(LspStdio.exitCode), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.logError(cause).pipe(Effect.andThen(Effect.fail(new LaunchFailed(Runtime.getErrorExitCode(Cause.squash(cause))))))), Effect.provideService(References.LogToStderr, true));
+	/**
+	* The teardown for `runMain`: a success hands its value on as the exit
+	* code when it is a number (0 otherwise), an interrupt-only exit maps to 0,
+	* and anything else goes to `Runtime.defaultTeardown`; then `host.exit`
+	* ends the process with that code.
+	*
+	* @remarks
+	* SIGINT and SIGTERM interrupt the program, and both exit 0 here, not the
+	* 130 a default teardown reports.
+	*
+	* The explicit exit is the point. The specification makes the server
+	* terminate on `exit` with stdin still open, but `runMain` ends the process
+	* itself only for a non-zero code or a signal, and leaves a code-0 exit to
+	* the event loop draining. It never drains while stdin is open: a server
+	* reading stdin through `NodeStdio` sits until the client closes the pipe
+	* (probed), which an editor never does first. Any other handle the server
+	* does not own holds it the same way, such as the client-liveness interval
+	* `vscode-languageserver`'s node entry installs under `--clientProcessId`.
+	*
+	* `host` is the process: `LspStdio.teardown(process)`. The package never
+	* reads `process` itself. A non-zero code is ended by `runMain` before
+	* `host.exit` is reached.
+	*/
+	static teardown(host) {
+		return (exit, onExit) => {
+			const code = Exit.isSuccess(exit) ? typeof exit.value === "number" ? exit.value : 0 : Cause.hasInterruptsOnly(exit.cause) ? 0 : void 0;
+			const finish = (resolved) => {
+				onExit(resolved);
+				host.exit(resolved);
+			};
+			return code === void 0 ? Runtime.defaultTeardown(exit, finish) : finish(code);
+		};
+	}
+};
+
+//#endregion
+export { LspStdio };

package/LspTestFailure.js

@@ -0,0 +1,37 @@
+import { Schema } from "effect";
+
+//#region src/LspTestFailure.ts
+/**
+* Why {@link LspProbe.initialize} could not prove a Language Server boots.
+*
+* @remarks
+* - `StreamEnded`: the server's stdout ended before the response the probe
+*   was waiting for, usually because it exited; a stream that ended inside a
+*   frame lands here too. The message carries the exit code and stderr.
+* - `InvalidFrame`: stdout carried bytes that are not an LSP frame — most
+*   often a log line written to stdout, which is the protocol wire. The
+*   message carries the frame error, excerpt included.
+* - `NotJsonRpc`: a well-framed body that is not a JSON-RPC 2.0 message.
+* - `TimedOut`: the exchange outlived `LspProbeOptions.timeout`. The message
+*   names the step the probe was waiting on and the stderr so far; a server
+*   that ignores `exit` and waits for stdin to close fails here.
+*
+* A JSON-RPC error answering `initialize` or `shutdown` is not a failure: it
+* is returned in the result for the caller to assert on.
+*
+* @public
+*/
+var LspTestFailure = class extends Schema.TaggedError()("LspTestFailure", {
+	/** Which failure occurred; see the list above. */
+	reason: Schema.Literals([
+		"StreamEnded",
+		"InvalidFrame",
+		"NotJsonRpc",
+		"TimedOut"
+	]),
+	/** A human-readable description of what went wrong. */
+	message: Schema.String
+}) {};
+
+//#endregion
+export { LspTestFailure };

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @effected/lsp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Language Server Protocol base-protocol framing for Effect v4 — `Content-Length` frames encoded by byte length and decoded incrementally — a stdio launcher that keeps stdout the LSP wire and exits with the code the specification requires, and a `./testing` subpath whose `LspProbe` proves a Language Server bin boots and whose `LspProcess` drives one frame by frame.
+
+[![npm](https://img.shields.io/npm/v/@effected%2Flsp?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/lsp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Install
+
+```bash
+npm install @effected/lsp effect
+```
+
+```bash
+pnpm add @effected/lsp effect
+```
+
+Requires Node.js >=24.11.0.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
+
+`effect` v4 is the only peer dependency. Boundary tier: the main entry is pure, and `./testing` runs a child process only through core's `ChildProcessSpawner`, which you provide with one platform layer (`NodeServices.layer` from `@effect/platform-node`).
+
+This is not an LSP server framework. It frames the wire, launches a server you wrote, and tests the bin; the message loop and every handler stay with whatever you serve the protocol with.
+
+## LspFrame
+
+An LSP message travels as a header block, a blank line, and a UTF-8 JSON body whose `Content-Length` counts **bytes**. A hand-rolled frame that writes `body.length` is right for ASCII and wrong by one for every extra byte of a multi-byte character, so the server reads into the next frame. `LspFrame.encode` counts the encoding:
+
+```ts
+import { LspFrame } from "@effected/lsp";
+
+const frame = LspFrame.encode({ jsonrpc: "2.0", method: "note", params: { text: "✓" } });
+console.log(new TextDecoder().decode(frame));
+// => Content-Length: 57
+//
+//    {"jsonrpc":"2.0","method":"note","params":{"text":"✓"}}
+```
+
+Decoding is incremental. `LspFrame.decodeResult` takes whatever bytes have arrived and returns every complete frame plus the bytes of an incomplete one, so a chunk may end inside a header, a body or a character, and may carry several frames. `LspFrame.decodeStream` threads that across a `Stream` of chunks, and `LspFrame.decodeAllResult` decodes a collected stdout in one go:
+
+```ts
+import { LspFrame } from "@effected/lsp";
+import { Result } from "effect";
+
+const decoded = LspFrame.decodeAllResult('Content-Length: 2\r\n\r\n{}Content-Length: 5\r\n\r\n"✓"');
+console.log(Result.getOrThrow(decoded));
+// => [ {}, '✓' ]
+```
+
+A malformed stream fails with a typed `LspFrameError` whose `code` says which rule broke (`MissingContentLength`, `InvalidContentLength`, `InvalidHeader`, `HeaderTooLarge`, `InvalidBody`, `Truncated`), whose `offset` is the frame's stream position, and whose `excerpt` echoes the frame's start — a log line written to stdout before the first frame shows up there verbatim. `decode` and `decodeAll` are the `Effect` forms.
+
+## LspStdio
+
+An Effect Language Server over stdio has three traps, and `LspStdio` closes each:
+
+- **`runMain` reports a failed program on stdout.** Its report runs outside every `Effect.provide` the program applies, so a `LogToStderr` provided inside never reaches it: a layer that fails to build (a missing `HOME`, a bad config) prints its report onto the wire. `LspStdio.launch` provides `LogToStderr` to the whole program, reports a failure on stderr itself, and re-raises it marked as already reported, keeping its exit code.
+- **The exit code is the specification's.** `exit` without a prior `shutdown` exits 1; everything else 0. `LspStdio.exitCode` is that rule, and `launch` applies it to the `LspSessionEnd` your message loop returns.
+- **A clean exit never happens on its own.** `runMain` ends the process itself only for a non-zero code or a signal, and leaves code 0 to the event loop draining, which it never does while stdin is open — and after `exit`, stdin is still open. `LspStdio.teardown(process)` ends the process explicitly, and maps SIGINT and SIGTERM to 0 instead of 130.
+
+```ts
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import { LspStdio } from "@effected/lsp";
+import { Effect } from "effect";
+import { AppLayer, serve } from "./server.js";
+
+// `serve` is your server: it runs the message loop and returns how the session ended.
+NodeRuntime.runMain(LspStdio.launch(serve.pipe(Effect.provide(AppLayer))), {
+  teardown: LspStdio.teardown(process),
+});
+```
+
+The kit does not own the message loop, so it cannot see `shutdown` or `exit` itself: your loop records them and returns `{ reason: "exit" | "closed", shutdownReceived }`. A `vscode-languageserver` connection reports both through `onShutdown` and `onExit`.
+
+`LogToStderr` reaches Effect's default logger and `Logger.consolePretty`. `Logger.consoleJson`, `consoleLogFmt` and `consoleStructured` write through `console.log` regardless — wrap a formatter in `Logger.withConsoleError` instead — and `Console.log` still writes to stdout.
+
+## LspProbe (`@effected/lsp/testing`)
+
+The packed-install proof for a Language Server bin, the twin of `@effected/mcp/testing`'s `McpProbe`. It spawns the command and runs the lifecycle an editor runs — `initialize`, `initialized`, `shutdown`, `exit` — then waits for the server to exit:
+
+```ts
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { LspProbe } from "@effected/lsp/testing";
+import { Effect } from "effect";
+import { ChildProcess } from "effect/process";
+
+const program = Effect.gen(function* () {
+  const probe = yield* LspProbe.initialize(ChildProcess.make("my-lsp", ["--stdio"]));
+  // A clean boot: no JSON-RPC error, exit code 0 (shutdown preceded exit), nothing on stderr.
+  return probe.response.error === undefined && probe.exitCode === 0 && probe.stderr === "";
+}).pipe(Effect.provide(NodeServices.layer));
+```
+
+- `initialize` goes out with `processId` and `rootUri` `null` and empty client capabilities unless `LspProbeOptions` says otherwise.
+- Stdin stays open after `exit`: the server must stop on `exit`, as it must under an editor. A server that waits for stdin to close fails with `TimedOut`.
+- Every message the server sent is in `messages`, in order; requests it sends to the client are recorded and never answered.
+- It never hangs: stdout that ends early fails `StreamEnded` with the exit code and stderr, bytes that are not frames fail `InvalidFrame`, and the whole exchange runs under `timeout` (30 seconds by default). Run it under `it.live` — the timeout reads `Clock`.
+
+## LspProcess (`@effected/lsp/testing`)
+
+A spawned server a test drives frame by frame — the LSP twin of `@effected/mcp/testing`'s `McpProcess`. The child lives for the enclosing scope:
+
+```ts
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { LspProcess } from "@effected/lsp/testing";
+import { Effect } from "effect";
+import { ChildProcess } from "effect/process";
+
+const program = Effect.gen(function* () {
+  const server = yield* LspProcess.spawn(ChildProcess.make("my-lsp", ["--stdio"]));
+  yield* server.send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { processId: null, rootUri: null, capabilities: {} } });
+  const { response, seen } = yield* server.readUntilResponse(1);
+  yield* server.send({ jsonrpc: "2.0", method: "initialized", params: {} });
+  yield* server.send({ jsonrpc: "2.0", id: 2, method: "shutdown" });
+  yield* server.readUntilResponse(2);
+  yield* server.send({ jsonrpc: "2.0", method: "exit" });
+  const exitCode = yield* server.exitCode;
+  // Stdout held nothing but frames: no stray byte before, between or after them.
+  const messages = yield* server.assertOnlyFrames;
+  return { response, seen, exitCode, messages };
+}).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
+```
+
+- `send` frames with `LspFrame.encode`; `sendRaw` writes bytes as given, for a malformed or split frame.
+- `nextMessage` and `readUntilResponse` never hang: stdout that ends fails `StreamEnded` (inside a frame too), bytes that are not a frame fail `InvalidFrame`, and a body that is not JSON-RPC fails `NotJsonRpc`.
+- `stderrUntil(predicate, { timeout })` waits for a report that lands on a later tick, woken by each stderr chunk rather than a polling timer, and fails `StreamEnded` or `TimedOut` with the stderr so far. Run it under `it.live`.
+- `stdoutSoFar` and `stdoutFinal` return the raw bytes; `assertOnlyFrames` waits for stdout to end and fails `InvalidFrame`, naming the offset and quoting the stray bytes, unless every byte belonged to a well-formed frame.
+
+## License
+
+MIT