@effected/lsp 0.0.0-stage → 0.1.1

package/index.d.ts

@@ -0,0 +1,315 @@
+import { Effect, Result, Runtime, Schema, Stream } from "effect";
+//#region src/LspFrame.d.ts
+/**
+ * Why a byte stream is not a sequence of LSP base-protocol frames.
+ *
+ * @remarks
+ * - `MissingContentLength`: the header block has no `Content-Length` field.
+ * - `InvalidContentLength`: a `Content-Length` that is not one decimal,
+ *   non-negative safe integer, or a second `Content-Length` field.
+ * - `InvalidHeader`: a header line that is not `Name: value`, or a header
+ *   byte outside ASCII. A server that writes a log line to stdout before its
+ *   first frame lands here, because the stray text joins the header block.
+ * - `HeaderTooLarge`: more than 8 KiB without the `\r\n\r\n` terminator. The
+ *   decoder refuses to buffer an unterminated header without bound.
+ * - `InvalidBody`: the body is not valid UTF-8 or not valid JSON.
+ * - `Truncated`: the input ended inside a frame.
+ *
+ * @public
+ */
+export declare const LspFrameErrorCode: Schema.Literals<readonly ["MissingContentLength", "InvalidContentLength", "InvalidHeader", "HeaderTooLarge", "InvalidBody", "Truncated"]>;
+/**
+ * The `code` of an {@link LspFrameError}.
+ *
+ * @public
+ */
+export type LspFrameErrorCode = typeof LspFrameErrorCode.Type;
+declare const LspFrameError_base: Schema.Class<LspFrameError, Schema.TaggedStruct<"LspFrameError", {
+  /** Which rule the frame broke; see {@link (LspFrameErrorCode:variable)}. */
+  readonly code: Schema.Literals<readonly ["MissingContentLength", "InvalidContentLength", "InvalidHeader", "HeaderTooLarge", "InvalidBody", "Truncated"]>;
+  /** The stream position of the offending frame's first byte. */
+  readonly offset: Schema.Number;
+  /** Up to 80 bytes of the frame's start, JSON-quoted. */
+  readonly excerpt: Schema.optionalKey<Schema.String>;
+  /** The UTF-8 or JSON failure behind an `InvalidBody`. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A byte stream that is not a sequence of LSP base-protocol frames.
+ *
+ * @remarks
+ * `offset` is the stream position of the offending frame's first byte, so a
+ * caller can point at it; `excerpt` echoes up to 80 bytes of the frame's
+ * start, JSON-quoted so control characters stay visible; `cause` carries the
+ * UTF-8 or JSON failure of an `InvalidBody` as the original value, never a
+ * stringified copy. `message` is derived from those fields when read.
+ *
+ * @public
+ */
+export declare class LspFrameError extends LspFrameError_base {
+  get message(): string;
+}
+/**
+ * What {@link LspFrame.decodeResult} decoded from one buffer.
+ *
+ * @public
+ */
+interface LspFrameDecoded {
+  /** Every complete frame's parsed JSON body, in order. */
+  readonly messages: ReadonlyArray<unknown>;
+  /** The bytes of an incomplete trailing frame, copied; prepend them to the next chunk. Empty when the buffer ended on a frame boundary. */
+  readonly rest: Uint8Array;
+}
+/**
+ * The LSP base protocol's framing: a `Content-Length` header block, a blank
+ * line, and a UTF-8 JSON body of exactly that many bytes.
+ *
+ * @remarks
+ * `Content-Length` counts **bytes**, never characters. A hand-rolled frame
+ * that writes `body.length` is correct for ASCII and wrong by one for every
+ * extra byte of a multi-byte character, so the server reads into the next
+ * frame and the session fails far from the cause; {@link LspFrame.encode}
+ * counts the UTF-8 encoding.
+ *
+ * The decoder is incremental and pure: {@link LspFrame.decodeResult} takes a
+ * buffer and returns every complete frame plus the bytes of an incomplete
+ * trailing one, so a chunk boundary may fall anywhere — inside a header,
+ * inside a body, inside a multi-byte character — and one chunk may carry
+ * several frames. {@link LspFrame.decodeStream} threads that state across a
+ * `Stream` of chunks.
+ *
+ * Header fields end `\r\n` and the block ends `\r\n\r\n`; field names are
+ * case-insensitive; unknown fields such as `Content-Type` are accepted and
+ * ignored. A header longer than 8 KiB without its terminator fails rather
+ * than buffering without bound.
+ *
+ * @example
+ * ```ts
+ * import { LspFrame } from "@effected/lsp";
+ * import { Result } from "effect";
+ *
+ * const bytes = LspFrame.encode({ jsonrpc: "2.0", method: "exit" });
+ * const decoded = LspFrame.decodeAllResult(bytes);
+ * console.log(Result.isSuccess(decoded) ? decoded.success : decoded.failure.message);
+ * // => [ { jsonrpc: '2.0', method: 'exit' } ]
+ * ```
+ *
+ * @public
+ */
+export declare class LspFrame {
+  private constructor();
+  /**
+   * Frame one message: `Content-Length: N\r\n\r\n` followed by its JSON text,
+   * where `N` is the UTF-8 byte length of that text.
+   *
+   * @remarks
+   * A value JSON cannot encode (a `bigint`, a cycle) is a caller bug and
+   * throws; nothing a server sends reaches this function.
+   */
+  static encode(message: unknown): Uint8Array;
+  /**
+   * Decode every complete frame at the front of `bytes`, returning their
+   * bodies and the bytes of an incomplete trailing frame.
+   *
+   * @remarks
+   * The sync primitive; {@link LspFrame.decode} is its spanned `Effect`
+   * form. `offset` is the stream position of `bytes[0]` (default 0), so an
+   * error names a stream position rather than a buffer index. To decode a
+   * stream by hand, keep `rest`, prepend it to the next chunk, and advance
+   * `offset` by the bytes consumed.
+   */
+  static decodeResult(bytes: Uint8Array, offset?: number): Result.Result<LspFrameDecoded, LspFrameError>;
+  /** The `Effect` form of {@link LspFrame.decodeResult}, behind the `LspFrame.decode` span. */
+  static readonly decode: (bytes: Uint8Array<ArrayBufferLike>, offset?: number | undefined) => Effect.Effect<LspFrameDecoded, LspFrameError, never>;
+  /**
+   * Decode a complete buffer — a collected stdout — into its messages.
+   *
+   * @remarks
+   * A string is UTF-8 encoded first, so its byte counts are honoured.
+   * Leftover bytes after the last complete frame fail `Truncated`. The sync
+   * primitive; {@link LspFrame.decodeAll} is the spanned `Effect` form.
+   */
+  static decodeAllResult(input: Uint8Array | string): Result.Result<ReadonlyArray<unknown>, LspFrameError>;
+  /** The `Effect` form of {@link LspFrame.decodeAllResult}, behind the `LspFrame.decodeAll` span. */
+  static readonly decodeAll: (input: string | Uint8Array<ArrayBufferLike>) => Effect.Effect<readonly unknown[], LspFrameError, never>;
+  /**
+   * Decode a stream of byte chunks into a stream of message bodies.
+   *
+   * @remarks
+   * Chunk boundaries may fall anywhere. A malformed frame fails the stream
+   * with an {@link LspFrameError}; a stream that ends inside a frame fails
+   * `Truncated`, so a server that dies mid-write is never read as a clean end.
+   */
+  static decodeStream<E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<unknown, E | LspFrameError, R>;
+}
+//#endregion
+//#region src/LspMessage.d.ts
+/**
+ * A JSON-RPC 2.0 message as an LSP frame body carries it: a request (an `id`
+ * and a `method`), a notification (a `method`, no `id`) or a response (an
+ * `id` and either `result` or `error`).
+ *
+ * @remarks
+ * Structural on purpose. Every field but `jsonrpc` is optional, because one
+ * shape describes all three kinds and the reader distinguishes them by which
+ * fields are present: `method` and `id` is a request, `method` alone is a
+ * notification, `id` without `method` is a response. A decoded frame body is
+ * `unknown` until a caller has checked it is one of these.
+ *
+ * @public
+ */
+interface LspMessage {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** Present on a request and a response; `null` on a response to a request whose id could not be read. */
+  readonly id?: number | string | null;
+  /** Present on a request and a notification. */
+  readonly method?: string;
+  /** A request's or notification's parameters. */
+  readonly params?: unknown;
+  /** A successful response's result; `null` is a valid result (`shutdown` answers it). */
+  readonly result?: unknown;
+  /** A failed response's error. */
+  readonly error?: {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+  };
+}
+//#endregion
+//#region src/LspStdio.d.ts
+/**
+ * How a Language Server session ended, as the server's own message loop
+ * observed it. {@link LspStdio.exitCode} maps it to the exit code the LSP
+ * specification requires.
+ *
+ * @remarks
+ * The kit does not own the message loop, so it cannot observe `shutdown` or
+ * `exit` itself: the server's loop records them and returns this value when
+ * it stops reading. A `vscode-languageserver` connection reports both through
+ * its `onShutdown` and `onExit` handlers; a hand-rolled loop sees the methods
+ * directly.
+ *
+ * @public
+ */
+interface LspSessionEnd {
+  /**
+   * `"exit"`: the client sent the `exit` notification. `"closed"`: stdin
+   * ended with no `exit` among the messages it delivered.
+   */
+  readonly reason: "exit" | "closed";
+  /** Whether a `shutdown` request arrived before the session ended. */
+  readonly shutdownReceived: boolean;
+}
+/**
+ * What {@link LspStdio.teardown} needs from the host: a way to end the
+ * process with a code. Node's `process` satisfies it.
+ *
+ * @public
+ */
+interface LspExitHost {
+  /** End the process with `code`. */
+  readonly exit: (code: number) => void;
+}
+/**
+ * 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
+ */
+export declare class LspStdio {
+  private 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: LspSessionEnd): 0 | 1;
+  /**
+   * 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 readonly launch: <E, R>(program: Effect.Effect<LspSessionEnd, E, R>) => Effect.Effect<0 | 1, Error, R>;
+  /**
+   * 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: LspExitHost): Runtime.Teardown;
+}
+//#endregion
+export type { LspExitHost, LspFrameDecoded, LspMessage, LspSessionEnd };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,4 @@
+import { LspFrame, LspFrameError, LspFrameErrorCode } from "./LspFrame.js";
+import { LspStdio } from "./LspStdio.js";
+
+export { LspFrame, LspFrameError, LspFrameErrorCode, LspStdio };

package/internal/LaunchFailed.js

@@ -0,0 +1,35 @@
+import { Runtime } from "effect";
+
+//#region src/internal/LaunchFailed.ts
+/**
+* The failure `LspStdio.launch` re-raises after reporting a failed server on
+* stderr itself. `errorReported: false` keeps `runMain` from reporting it a
+* second time — through a logger that writes to stdout, the LSP wire — and the
+* original exit code rides along for the teardown.
+*
+* @remarks
+* Both runtime markers are prototype getters rather than own fields, so a JSON
+* or logger dump of the error does not carry them; the code lives in a private
+* field.
+*
+* @internal
+*/
+var LaunchFailed = class extends Error {
+	#code;
+	constructor(code) {
+		super(`the language server failed (exit ${code})`);
+		this.name = "LaunchFailed";
+		this.#code = code;
+	}
+	/** Already reported on stderr: `runMain` must not report it again. */
+	get [Runtime.errorReported]() {
+		return false;
+	}
+	/** The exit code the server failed with. */
+	get [Runtime.errorExitCode]() {
+		return this.#code;
+	}
+};
+
+//#endregion
+export { LaunchFailed };

package/internal/messages.js

@@ -0,0 +1,30 @@
+import { LspTestFailure } from "../LspTestFailure.js";
+
+//#region src/internal/messages.ts
+/** How much text a failure message echoes. */
+const ECHO = 2e3;
+/**
+* Cut `text` to the echo limit, marking the cut.
+*
+* @internal
+*/
+const truncate = (text) => text.length <= ECHO ? text : `${text.slice(0, ECHO)}…`;
+/**
+* A JSON object whose `jsonrpc` is `"2.0"`; a reader tells the three kinds
+* apart by their fields.
+*
+* @internal
+*/
+const isLspMessage = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && value.jsonrpc === "2.0";
+/**
+* The `NotJsonRpc` failure for a well-framed body that is no JSON-RPC 2.0 message.
+*
+* @internal
+*/
+const notJsonRpc = (message) => new LspTestFailure({
+	reason: "NotJsonRpc",
+	message: `the server sent a frame that is not a JSON-RPC 2.0 message: ${truncate(JSON.stringify(message) ?? String(message))}`
+});
+
+//#endregion
+export { isLspMessage, notJsonRpc, truncate };

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@effected/lsp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/lsp",
+	"version": "0.1.1",
+	"private": false,
+	"description": "Language Server Protocol base-protocol framing for Effect v4, plus a packed-install initialize probe for a Language Server bin",
+	"keywords": [
+		"effect",
+		"lsp",
+		"language-server-protocol",
+		"json-rpc",
+		"content-length",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/lsp#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/lsp"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "^4.0.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}