@dsh-stack/lsp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# 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.
+DeepSeek Harness (`dsh`) plugin: owns the LSP capability on the web profile.
+
+The harness ships the LSP service definition (`ctx.lsp`), a generic stdio
+provider (`dsh-lsp-stdio`), and a model-facing `lsp` tool (`dsh-tool-lsp`), but
+composes none of them by default. This plugin mounts the trio and feeds the
+stdio provider the server table from the `lsp` settings section, so the
+agent's `goToDefinition` / `findReferences` / `goToImplementation` / `hover`
+queries work out of the box.
+
+## Settings
+
+`lsp:` section of `settings.yaml`:
+
+```yaml
+lsp:
+  servers:
+    typescript:
+      command: typescript-language-server
+      extensionToLanguage: { ".ts": typescript, ".tsx": typescriptreact }
+      args: [--stdio]
+```
+
+Server entries follow `LspLocalServerConfig` from `@deepseek-ai/dsh-lsp-stdio`.
+Changes apply on the next boot (mounts are boot-time, not hot-reloaded).
+
+## CLI
+
+```
+dsh lsp list
+dsh lsp servers add <id> <command> [--ext=.ts=typescript] [--args=a b c]
+dsh lsp servers remove <id>
+```
+
+## Layout
+
+- `src/settings.ts` — the `lsp` settings namespace and server entry schema.
+- `src/index.ts` — plugin: settings section + mounting the LSP trio.
+- `bin/lsp.mjs` — the `dsh lsp` CLI.
+- `check-plugin.mjs` — boot-verify harness (`npm test`).

package/bin/lsp.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// jscpd:ignore-start -- per-package CLI entrypoint boilerplate (arg parsing, help text), duplicated by design across sibling CLI packages
+/**
+ * The `dsh lsp` command: the owner surface over the lsp server table. It
+ * reads/writes the `lsp` section of `settings.yaml` under the same agent
+ * home the harness boots (DSH_HOME); the plugin mounts those servers on the
+ * next boot.
+ *
+ * Verbs:
+ *   list                       — installed LSP servers (id, command, extensions)
+ *   servers add <id> <command> — add a stdio server (--ext=.ts=typescript, --args=...)
+ *   servers remove <id>        — delete a server entry
+ */
+
+import { homedir } from "node:os";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+const home = resolve(process.env.DSH_HOME ?? join(homedir(), ".agents"));
+const settingsPath = join(home, "settings.yaml");
+
+/** readSection implementation. */
+function* readSection(text, section) {
+  let inSection = false;
+  for (const line of text.split("\n")) {
+    if (new RegExp(`^${section}\\s*:`).test(line)) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && !/^\s/.test(line)) break;
+    if (!inSection) continue;
+    const match = line.match(/^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (match) {
+      yield [match[1], match[2].trim().replace(/^(['"])(.*)\1$/, "$2")];
+    }
+  }
+}
+
+/** parseJsonValue implementation. */
+function parseJsonValue(raw) {
+  if (raw === "" || raw === "null") return null;
+  if (raw[0] === "{" || raw[0] === "[") {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      /* fall through */
+    }
+  }
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  const num = Number(raw);
+  if (raw !== "" && Number.isFinite(num)) return num;
+  return raw;
+}
+
+/** readServers implementation. */
+async function readServers() {
+  try {
+    const text = await readFile(settingsPath, "utf8");
+    const section = {};
+    for (const [key, value] of readSection(text, "lsp")) {
+      section[key] = parseJsonValue(value);
+    }
+    return section;
+  } catch {
+    /* no document yet */
+  }
+  return {};
+}
+
+/** writeServers implementation. */
+async function writeServers(servers) {
+  let text = "";
+  try {
+    text = await readFile(settingsPath, "utf8");
+  } catch {
+    /* new file */
+  }
+  const pattern = /^lsp[^\n]*\n(?:[ \t][^\n]*\n)*/m;
+  const section = `lsp:\n  servers: ${JSON.stringify(servers.servers ?? {})}\n`;
+  const without = text.replace(pattern, "");
+  const rest = without.replace(/\n{3,}/g, "\n\n").trim();
+  const out = `${rest}${rest.endsWith("\n") ? "" : "\n"}${section}`;
+  await mkdir(dirname(settingsPath), { recursive: true });
+  await writeFile(settingsPath, out, "utf8");
+}
+
+/** printHelp implementation. */
+function printHelp() {
+  process.stdout.write(`usage: dsh lsp <verb> [args]
+
+verbs:
+  list
+  servers add <id> <command> [--ext=.ts=typescript] [--args=a b c]
+  servers remove <id>
+`);
+}
+
+/** main implementation. */
+async function main() {
+  const verb = process.argv[2];
+  const argv = process.argv.slice(3);
+
+  if (verb === "list") {
+    const servers = await readServers();
+    const entries = Object.entries(servers.servers ?? {});
+    if (entries.length === 0) {
+      process.stdout.write("no LSP servers configured\n");
+      return;
+    }
+    for (const [id, cfg] of entries) {
+      const ext = Object.keys(cfg.extensionToLanguage ?? {}).join(",") || "—";
+      process.stdout.write(`${id}    ${cfg.command}    ${ext}\n`);
+    }
+    return;
+  }
+
+  if (verb === "servers" && argv[0] === "add") {
+    const id = argv[1];
+    const command = argv[2];
+    if (!id || !command) {
+      process.stderr.write("dsh lsp servers add: missing id or command\n");
+      process.exitCode = 1;
+      return;
+    }
+    const extensionToLanguage = {};
+    const args = [];
+    for (const arg of argv.slice(3)) {
+      if (arg.startsWith("--ext=")) {
+        const spec = arg.slice(6);
+        const [ext, lang] = spec.split("=");
+        if (ext && lang) extensionToLanguage[ext] = lang;
+      } else if (arg.startsWith("--args=")) {
+        args.push(...arg.slice(7).split(" ").filter(Boolean));
+      }
+    }
+    const servers = await readServers();
+    const table = servers.servers ?? {};
+    table[id] = { command, extensionToLanguage, ...(args.length > 0 ? { args } : {}) };
+    await writeServers({ ...servers, servers: table });
+    process.stdout.write(`added LSP server ${id} -> ${command}\n`);
+    return;
+  }
+
+  if (verb === "servers" && argv[0] === "remove") {
+    const id = argv[1];
+    if (!id) {
+      process.stderr.write("dsh lsp servers remove: missing id\n");
+      process.exitCode = 1;
+      return;
+    }
+    const servers = await readServers();
+    const table = servers.servers ?? {};
+    if (table[id] === undefined) {
+      process.stderr.write(`dsh lsp servers remove: no server "${id}"\n`);
+      process.exitCode = 1;
+      return;
+    }
+    delete table[id];
+    await writeServers({ ...servers, servers: table });
+    process.stdout.write(`removed LSP server ${id}\n`);
+    return;
+  }
+
+  printHelp();
+}
+
+main().catch((err) => {
+  process.stderr.write(`dsh lsp: ${err.message}\n`);
+  process.exitCode = 1;
+});
+
+// jscpd:ignore-end

package/lib/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `lsp`: owns the LSP capability on the web profile. The harness ships the
+ * LSP service definition (`ctx.lsp`), a generic stdio provider
+ * (`dsh-lsp-stdio`), and a model-facing `lsp` tool (`dsh-tool-lsp`) — but
+ * composes none of them by default, and its LSP operation set is a closed
+ * compile-time union (no formatting: that is `formatters`' job). This
+ * plugin mounts the trio through `ctx.plugin` and feeds the stdio provider
+ * the server table this plugin's own Config carries, so the agent's
+ * `goToDefinition`/`findReferences`/`goToImplementation`/`hover` queries work
+ * out of the box. The `dsh lsp` CLI (bin/lsp.mjs) manages the table; changes
+ * apply on the next boot (mounts are boot-time, not hot-reloaded).
+ * @module lsp
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import { LspConfig } from "./settings.js";
+export type * from "./settings.js";
+export declare const name = "lsp";
+export declare const inject: string[];
+/** Re-exported bare, not as `z<LspConfig>` — see `settings.ts`. */
+export declare const Config: import("@deepseek-ai/schemastery").default<import("./settings.js").LspServerInput, LspConfig, "plain">;
+/**
+ * Mount the LSP service definition, the stdio provider (only when at least one
+ * server is configured — `lsp-stdio` refuses an empty table), and the
+ * model-facing tool.
+ *
+ * Since 0.2.0 there is no separate settings section to read: this plugin's
+ * `Config` is the `lsp` form the settings service projects, under this entry's
+ * own id as its namespace, so `config.servers` is the one server table — entry
+ * values and profile edits alike arrive through it. It is a live reference the
+ * Loader commits settings writes into, so it is read through `installedServers`
+ * at mount rather than snapshotted. The mounts stay boot-time, so a table edited
+ * after boot takes effect on the next boot, the same contract the `dsh lsp` CLI
+ * documents.
+ *
+ * @param ctx - the plugin context.
+ * @param config - the plugin's live configuration, carrying the LSP server table.
+ */
+export declare function apply(ctx: Context, config: LspConfig): void;

package/lib/index.js

@@ -0,0 +1,56 @@
+/**
+ * `lsp`: owns the LSP capability on the web profile. The harness ships the
+ * LSP service definition (`ctx.lsp`), a generic stdio provider
+ * (`dsh-lsp-stdio`), and a model-facing `lsp` tool (`dsh-tool-lsp`) — but
+ * composes none of them by default, and its LSP operation set is a closed
+ * compile-time union (no formatting: that is `formatters`' job). This
+ * plugin mounts the trio through `ctx.plugin` and feeds the stdio provider
+ * the server table this plugin's own Config carries, so the agent's
+ * `goToDefinition`/`findReferences`/`goToImplementation`/`hover` queries work
+ * out of the box. The `dsh lsp` CLI (bin/lsp.mjs) manages the table; changes
+ * apply on the next boot (mounts are boot-time, not hot-reloaded).
+ * @module lsp
+ */
+import { declareCustomSettingsPage } from "@dsh-stack/plugin-kit";
+import Lsp from "@deepseek-ai/dsh-lsp";
+import * as LspStdio from "@deepseek-ai/dsh-lsp-stdio";
+import * as ToolLsp from "@deepseek-ai/dsh-tool-lsp";
+import { installedServers, LspConfig } from "./settings.js";
+export const name = "lsp";
+export const inject = [];
+/** Re-exported bare, not as `z<LspConfig>` — see `settings.ts`. */
+export const Config = LspConfig;
+/**
+ * Mount the LSP service definition, the stdio provider (only when at least one
+ * server is configured — `lsp-stdio` refuses an empty table), and the
+ * model-facing tool.
+ *
+ * Since 0.2.0 there is no separate settings section to read: this plugin's
+ * `Config` is the `lsp` form the settings service projects, under this entry's
+ * own id as its namespace, so `config.servers` is the one server table — entry
+ * values and profile edits alike arrive through it. It is a live reference the
+ * Loader commits settings writes into, so it is read through `installedServers`
+ * at mount rather than snapshotted. The mounts stay boot-time, so a table edited
+ * after boot takes effect on the next boot, the same contract the `dsh lsp` CLI
+ * documents.
+ *
+ * @param ctx - the plugin context.
+ * @param config - the plugin's live configuration, carrying the LSP server table.
+ */
+export function apply(ctx, config) {
+    declareCustomSettingsPage(ctx);
+    ctx.inject(["settings"], async () => {
+        const servers = installedServers(config);
+        if (ctx.get("lsp") === undefined) {
+            await ctx.plugin(Lsp);
+        }
+        if (Object.keys(servers).length > 0) {
+            await ctx.plugin(LspStdio, { servers });
+            await ctx.plugin(ToolLsp, {});
+            ctx.logger.info(`lsp: mounted ${Object.keys(servers).length} LSP server(s)`);
+        }
+        else {
+            ctx.logger.warn("lsp: no LSP servers configured — run `dsh lsp servers add <id> <command>`");
+        }
+    });
+}

package/lib/settings.d.ts

@@ -0,0 +1,72 @@
+/**
+ * lsp settings: the `lsp` entry owns the LSP server table. The plugin mounts
+ * the harness LSP capability (service definition, the stdio provider with this
+ * table, and the model-facing `lsp` tool) on the web profile, so
+ * `goToDefinition`/`findReferences`/`goToImplementation`/`hover` work for the
+ * agent without touching the pristine harness.
+ *
+ * Since 0.2.0 there is no second section schema to register: this plugin's own
+ * `Config` is the form the settings service projects, and its namespace is this
+ * entry's own id. So one schema, `LspConfig`, carries both roles. Which of its
+ * fields that form shows is decided by volatility: the server table is the
+ * user's choice — which language servers exist and how to launch them — so it is
+ * declared `.volatile()`, and it is the whole of the table rather than just the
+ * list of ids. The settings service only recurses into `object` schemas when it
+ * projects a form, so a volatile marker nested inside the table's entries would
+ * leave `servers` itself unprojected; marking the dictionary is what makes the
+ * form exist, and it is what lets the user edit a server's command rather than
+ * only add and remove ids.
+ * @module lsp/settings
+ */
+import type { Volatile } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import type { LspLocalServerConfig } from "@deepseek-ai/dsh-lsp-stdio";
+/** Namespace of the LSP server table — this plugin's own Loader entry id. */
+export declare const NS: import("@dsh-stack/plugin-kit").SettingsNamespace;
+/** One stdio language server the plugin mounts through `dsh-lsp-stdio`. */
+export type LspServerEntry = LspLocalServerConfig;
+export declare const LspServerEntry: z<LspServerEntry>;
+/** The plugin's configuration — and, since 0.2.0, its own settings form. */
+export interface LspConfig {
+    /**
+     * Lowercase leading-dot extension → installed stdio server. Volatile because
+     * the answer is machine-local: which language servers exist, under what ids and
+     * with what commands, differs per workstation, so no deployment can pin one
+     * correct table and the user owns it. It is volatile as one whole-dictionary
+     * node — not a marker per table entry — because the settings service only
+     * recurses into `object` schemas when it projects a form, and because a form
+     * write can only address a path lying under a volatile node: a reference per
+     * entry could be neither declared nor edited, and marking only the ids would
+     * leave the command a client cannot correct.
+     */
+    servers: Volatile<Record<string, LspServerEntry>>;
+}
+/** What the server-table schema accepts before validation. */
+export type LspServerInput = {
+    servers: Record<string, LspServerEntry>;
+};
+/**
+ * Not annotated `z<LspConfig>`: a volatile field's output type is `Volatile<T>`,
+ * which `z<T>`'s invariant position cannot hold. The three-parameter schema
+ * type is the annotation that can, and it is required rather than cosmetic —
+ * left to inference, the nested `Volatile` inside this dictionary has no name
+ * the declaration emitter can write (`TS2742`), and `themes`/`formatters` get
+ * away with a bare `z.object({...})` only because their volatile fields are
+ * scalar. `harness`'s own `llm-pi-ai` uses the same bare shape and builds with
+ * a different declaration emitter.
+ */
+export declare const LspConfig: z<LspServerInput, LspConfig, "plain">;
+/**
+ * The servers currently installed for this entry, in the mutable shape
+ * `dsh-lsp-stdio` declares.
+ *
+ * Reads the volatile field at call time, so a settings write is visible to the
+ * next read rather than to a value captured at boot. `args` is copied because a
+ * volatile snapshot is deeply frozen and the stdio provider's own Config declares
+ * a mutable `string[]` there; the plain properties and index signatures need no
+ * such copy, as TypeScript does not compare them for `readonly`.
+ *
+ * @param config - the plugin's projected Config.
+ * @returns the installed server table, empty when none is configured.
+ */
+export declare function installedServers(config: LspConfig | undefined): Record<string, LspServerEntry>;

package/lib/settings.js

@@ -0,0 +1,69 @@
+/**
+ * lsp settings: the `lsp` entry owns the LSP server table. The plugin mounts
+ * the harness LSP capability (service definition, the stdio provider with this
+ * table, and the model-facing `lsp` tool) on the web profile, so
+ * `goToDefinition`/`findReferences`/`goToImplementation`/`hover` work for the
+ * agent without touching the pristine harness.
+ *
+ * Since 0.2.0 there is no second section schema to register: this plugin's own
+ * `Config` is the form the settings service projects, and its namespace is this
+ * entry's own id. So one schema, `LspConfig`, carries both roles. Which of its
+ * fields that form shows is decided by volatility: the server table is the
+ * user's choice — which language servers exist and how to launch them — so it is
+ * declared `.volatile()`, and it is the whole of the table rather than just the
+ * list of ids. The settings service only recurses into `object` schemas when it
+ * projects a form, so a volatile marker nested inside the table's entries would
+ * leave `servers` itself unprojected; marking the dictionary is what makes the
+ * form exist, and it is what lets the user edit a server's command rather than
+ * only add and remove ids.
+ * @module lsp/settings
+ */
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@dsh-stack/plugin-kit";
+/** Namespace of the LSP server table — this plugin's own Loader entry id. */
+export const NS = settingsNamespace("lsp");
+export const LspServerEntry = z.object({
+    command: z.string().required(),
+    extensionToLanguage: z.dict(String).required(),
+    args: z.array(String).default([]),
+    env: z.dict(String).default({}),
+    initializationOptions: z.any().default(null),
+    configuration: z.any().default(null),
+    maxMessageBytes: z.number().default(16_000_000),
+    maxStderrBytes: z.number().default(1_000_000),
+    maxDocumentBytes: z.number().default(4_000_000),
+    shutdownTimeoutMs: z.number().default(5_000),
+    killGraceMs: z.number().default(2_000),
+});
+/**
+ * Not annotated `z<LspConfig>`: a volatile field's output type is `Volatile<T>`,
+ * which `z<T>`'s invariant position cannot hold. The three-parameter schema
+ * type is the annotation that can, and it is required rather than cosmetic —
+ * left to inference, the nested `Volatile` inside this dictionary has no name
+ * the declaration emitter can write (`TS2742`), and `themes`/`formatters` get
+ * away with a bare `z.object({...})` only because their volatile fields are
+ * scalar. `harness`'s own `llm-pi-ai` uses the same bare shape and builds with
+ * a different declaration emitter.
+ */
+export const LspConfig = z.object({
+    servers: z.dict(LspServerEntry).default({}).volatile(),
+});
+/**
+ * The servers currently installed for this entry, in the mutable shape
+ * `dsh-lsp-stdio` declares.
+ *
+ * Reads the volatile field at call time, so a settings write is visible to the
+ * next read rather than to a value captured at boot. `args` is copied because a
+ * volatile snapshot is deeply frozen and the stdio provider's own Config declares
+ * a mutable `string[]` there; the plain properties and index signatures need no
+ * such copy, as TypeScript does not compare them for `readonly`.
+ *
+ * @param config - the plugin's projected Config.
+ * @returns the installed server table, empty when none is configured.
+ */
+export function installedServers(config) {
+    return Object.fromEntries(Object.entries(config?.servers?.get() ?? {}).map(([id, entry]) => [
+        id,
+        { ...entry, args: [...(entry.args ?? [])] },
+    ]));
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@dsh-stack/lsp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "LSP server configuration + dsh lsp CLI for the DeepSeek Harness LSP capability seam",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node check-plugin.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-lsp": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-lsp-stdio": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-lsp": "0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.0.0"
+  },
+  "dependencies": {
+    "@dsh-stack/plugin-kit": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-lsp": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-lsp-stdio": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-lsp": "0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.0.0"
+  },
+  "stack": {
+    "kind": "plugin",
+    "id": "stack.dev.lsp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marius-patrik/dsh-stack.git",
+    "directory": "plugins/lsp"
+  }
+}