@lensmap/language-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lensmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @lensmap/language-server
 
-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.
+Experimental Lensmap stdio language server and authenticated loopback browser
+preview. Includes its compiled browser assets; npm installs the document engine
+and other runtime dependencies before startup. No workspace checkout, pnpm,
+Rust, runtime dependency download or separate web server is needed to run it.
+
+Requires Node 24.16 or newer. ESM only. The API and document format are
+experimental. Native host integration is currently qualified on Linux/X11;
+other platforms are not yet qualified. Automatic browser launching uses
+`xdg-open`; `--no-open` leaves opening the preview URL to the host/client.
+
+```sh
+npm install --global @lensmap/language-server@next
+lensmap-lsp --help
+lensmap-lsp --configure-zed --zed /usr/bin/zeditor
+```
+
+The last command **prints** settings, without modifying your editor. Use your
+verified Zed executable path. Keep the Node installation and package path stable,
+and regenerate settings if either changes. Zed still requires the separately
+installed Lensmap **dev extension** from the source repository's `editors/zed`
+directory; the npm package does not install or register an editor extension.
+
+The editor launches `lensmap-lsp --stdio`. Its stdout is reserved for LSP; it is
+not a standalone saved-file viewer or persistent background web daemon. Attach a
+`.lensmap` buffer and invoke **Lensmap: Open preview** through editor code
+actions. The server defaults to its package-local built viewer. `--assets PATH`
+remains available for development/custom assets.
+
+Preview URLs and API tokens are private per-run credentials. Do not log, paste
+or retain them in traces. The server binds to loopback, validates Host/Origin,
+and limits source access to attached buffers. Content writes use revision checks
+and live-buffer readback, **not atomic compare-and-swap**.
+
+See [Zed setup, API and limitations](https://github.com/nicodoggie/lensmap/blob/main/docs/zed-browser.md).
+The library export exposes `startServer` and its TypeScript declarations; custom
+hosts supply their own `assets` and host callbacks. MIT licensed; see `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { RevealTarget, ServerHandle, ServerOptions } from "./server.js";
+export { startServer } from "./server.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { startServer } from "./server.js";

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { startServer } from "./server.js";
+const { values } = parseArgs({
+    options: {
+        stdio: { type: "boolean" },
+        assets: { type: "string" },
+        zed: { type: "string", default: "zeditor" },
+        "zed-data-dir": { type: "string" },
+        "no-open": { type: "boolean" },
+        "configure-zed": { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+const assets = resolve(values.assets ?? resolve(import.meta.dirname, "preview"));
+if (values.help) {
+    process.stdout.write("Lensmap experimental language server + loopback preview\n\nUsage: lensmap-lsp --stdio [--assets PATH] [--zed EXECUTABLE]\n  --assets PATH     Override the bundled browser preview assets\n  --no-open          Return preview links without launching a browser\n  --zed-data-dir DIR  Target a private Zed profile for source reveal\n  --configure-zed    Print workspace settings for the local dev extension\n\nInstalled packages include the browser preview. For source checkouts, run pnpm build.\nPreview URLs/tokens are private per-run credentials; retrieve them through\nLensmap's code actions or lensmap.session LSP command.\nEditor writes use revision checks/readback, not atomic compare-and-swap.\n");
+}
+else if (values["configure-zed"]) {
+    process.stdout.write(`${JSON.stringify({
+        file_types: { YAML: ["lensmap"] },
+        languages: { YAML: { language_servers: ["lensmap", "..."] } },
+        lsp: {
+            lensmap: {
+                binary: {
+                    path: process.execPath,
+                    arguments: [
+                        fileURLToPath(import.meta.url),
+                        "--stdio",
+                        "--assets",
+                        assets,
+                        "--zed",
+                        values.zed,
+                    ],
+                },
+            },
+        },
+    }, null, 2)}\n`);
+}
+else {
+    const launch = (executable, args) => new Promise((done, reject) => {
+        const child = spawn(executable, args, { stdio: "ignore" });
+        child.once("error", () => reject(new Error("Host opener could not start.")));
+        child.once("exit", (code) => code === 0 ? done() : reject(new Error("Host opener failed.")));
+    });
+    const reveal = async ({ uri, range, source }) => {
+        if (!uri.startsWith("file:"))
+            throw new Error("This host reveals attached file documents only.");
+        const line = source.split("\n")[range.start.line] ?? "";
+        const column = Buffer.byteLength(line.slice(0, range.start.character), "utf8") + 1;
+        const location = `${fileURLToPath(uri)}:${range.start.line + 1}:${column}`;
+        await launch(values.zed ?? "zeditor", [
+            ...(values["zed-data-dir"]
+                ? ["--user-data-dir", values["zed-data-dir"]]
+                : []),
+            "--existing",
+            location,
+        ]);
+    };
+    try {
+        const server = await startServer({
+            input: process.stdin,
+            output: process.stdout,
+            assets,
+            reveal,
+            open: values["no-open"]
+                ? undefined
+                : async (url) => {
+                    if (process.platform !== "linux")
+                        throw new Error("Browser launching is currently qualified on Linux only; use the returned preview URL.");
+                    await launch("xdg-open", [url]);
+                },
+        });
+        process.stderr.write(`Lensmap ready at ${server.origin}; use the Open preview code action.\n`);
+        const stop = () => {
+            void server.close().finally(() => {
+                process.stdin.destroy();
+            });
+        };
+        process.once("SIGTERM", stop);
+        process.once("SIGINT", stop);
+    }
+    catch {
+        process.stderr.write("Lensmap could not start. Check the preview asset directory; rebuild source checkouts with pnpm build or reinstall the npm package. See --help.\n");
+        process.exitCode = 1;
+    }
+}