@xuanling-rs/xuanling-dsh-tools 0.2.2 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umbrella22 and XuanLing 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-ZH.md

@@ -0,0 +1,28 @@
+# xuanling-dsh-tools
+
+[English](README.md) | 简体中文
+
+这是完整 XuanLing MCP catalog 的增量式 DeepSeek Harness bundle。它保留全部 Harness
+原生工具，并以 `mcp__xuanling__` 前缀增加 XuanLing 工具。
+
+```sh
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.2.4
+```
+
+该命令会扩展 DSH 内置的 Web profile。内置 Headless profile 应使用 `--profile headless`。
+未知 profile 名称只包含 base bundle，本身不会提供可运行的 Web 或 Headless 应用。
+
+精确版本的 `@xuanling-rs/xuanling-mcp@0.2.4` runtime 会安装在 profile 内，并通过带校验的 JS launcher
+启动；不需要也不会使用全局 npm package。只有文件系统 capability root 与 DSH 工作目录不同时，
+才需要设置 `XUANLING_WORKSPACE_ROOT`。
+
+该 bundle 的 result adapter 会保留完整 Native 文本投影，只删除与 `structuredContent` 完全重复的
+意外文本块。
+
+Adapter 只接受子进程 JSON object frame。输出 malformed 或子进程正常退出时仍有未结算 request 会以非零状态
+结束；Host 终止信号会被转发，子进程未在 500 ms grace 内退出时会被强制终止。
+
+该包会与 DSH 原生文件、进程和项目工具产生能力重叠。日常配置建议使用目录更小的
+`@xuanling-rs/xuanling-dsh-memory`。不要在同一 profile 内安装多个 XuanLing 工具 bundle。
+
+要求 Node.js 22.14 或更高版本。使用 MIT License。

package/README.md

@@ -0,0 +1,34 @@
+# xuanling-dsh-tools
+
+English | [Simplified Chinese](README-ZH.md)
+
+Additive DeepSeek Harness bundle for the complete XuanLing MCP catalog. It
+keeps all Harness-native tools enabled and adds XuanLing tools under the
+`mcp__xuanling__` prefix.
+
+```sh
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.2.4
+```
+
+This command augments DSH's shipped Web profile. Use `--profile headless` for
+the shipped Headless profile. Unknown profile names start with the base bundle
+only and do not provide a runnable Web or Headless application by themselves.
+
+The exact `@xuanling-rs/xuanling-mcp@0.2.4` runtime is installed in the profile and started
+through its verified JS launcher. A global npm package is neither required nor
+used. Set `XUANLING_WORKSPACE_ROOT` only when the filesystem capability root
+must differ from the DSH working directory.
+
+The bundle's result adapter preserves the complete Native text projection and
+removes only accidental duplicate text blocks that exactly repeat
+`structuredContent`.
+
+The adapter accepts only JSON object frames from the child. Malformed output or
+an unresolved request at clean child exit returns a nonzero status; host
+termination is forwarded and force-terminated after a 500 ms grace when needed.
+
+This package overlaps with native file, process, and project tools. Prefer
+`@xuanling-rs/xuanling-dsh-memory` for the smaller daily tool surface. Do not install this
+package with another XuanLing tool bundle in the same profile.
+
+Node.js 22.14 or newer is required. Licensed under the MIT License.

package/cordis.patch.yml

@@ -0,0 +1,34 @@
+# XuanLing tools for DeepSeek Harness — additive variant.
+#
+# Mounts the xuanling-mcp binary through the local result adapter and the
+# official @deepseek-ai/dsh-mcp-client bridge. Every XuanLing tool becomes a native
+# harness tool named mcp__xuanling__<raw> (for example mcp__xuanling__fs_read_text);
+# the bridge owns reconnect, re-sync, and generation rollback. Built-in tools
+# (read/write/edit/glob/grep/bash/…) stay registered — this variant only ADDS.
+#
+# The bundle resolves its exact result adapter and xuanling-mcp dependency from
+# the DSH profile. The JS launcher then selects and verifies the matching native
+# package; the adapter preserves one complete text projection and structured value.
+#
+# The filesystem capability root defaults to the directory dsh was started
+# from; override with XUANLING_WORKSPACE_ROOT. Memory uses the shared default
+# database (~/.xuanling/memory.db) exactly like the ZCode plugin deployment.
+# The ZCode-only object-parameter compat shim stays OFF everywhere in this
+# integration: DeepSeek forwards model arguments as verbatim JSON.
+
+- insert:
+    - id: xuanling-tools
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: xuanling
+        transport: stdio
+        command: !!js process.execPath
+        args:
+          - !!js process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@xuanling-rs/xuanling-dsh-tools/mcp-result-adapter.mjs')
+          - '--binary'
+          - !!js process.execPath
+          - '--'
+          - !!js process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@xuanling-rs/xuanling-mcp/bin/xuanling-mcp.js')
+          - '--workspace-root'
+          - !!js process.env.XUANLING_WORKSPACE_ROOT ?? process.cwd()
+        toolCallTimeoutMs: 120000

package/mcp-result-adapter.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { isDeepStrictEqual } from "node:util";
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+import { pathToFileURL } from "node:url";
+
+const TEXT_RESULT_DUPLICATE_LIMIT = 1;
+const CHILD_TERMINATION_GRACE_MS = 500;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function requestIdKey(id) {
+  return `${typeof id}:${JSON.stringify(id)}`;
+}
+
+function parseFrame(line) {
+  try {
+    const frame = JSON.parse(line);
+    return isRecord(frame) ? frame : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function validateChildFrame(line) {
+  if (!parseFrame(line)) throw new Error("invalid JSON or malformed child frame");
+}
+
+export function requestMethodAndId(line) {
+  const frame = parseFrame(line);
+  if (!frame || typeof frame.method !== "string" || !Object.hasOwn(frame, "id")) return undefined;
+  return { id: requestIdKey(frame.id), method: frame.method };
+}
+
+function parsedJsonText(text) {
+  if (typeof text !== "string") return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function matchesStructuredContent(block, structuredContent) {
+  if (!isRecord(block) || block.type !== "text") return false;
+  const parsed = parsedJsonText(block.text);
+  return parsed.ok && isDeepStrictEqual(parsed.value, structuredContent);
+}
+
+/**
+ * DSH keeps the complete text projection for Native/model rendering. If a
+ * server or an intermediate bridge accidentally emits the same structured
+ * JSON text block more than once, retain one copy and preserve the canonical
+ * structured value for Code Mode and output validation.
+ */
+export function projectDshCallResult(result) {
+  if (!isRecord(result) || !Array.isArray(result.content) || !Object.hasOwn(result, "structuredContent")) {
+    return result;
+  }
+
+  const matching = result.content.filter((block) =>
+    matchesStructuredContent(block, result.structuredContent),
+  );
+  if (matching.length <= TEXT_RESULT_DUPLICATE_LIMIT) return result;
+
+  let retained = false;
+  const content = result.content.filter((block) => {
+    if (!matchesStructuredContent(block, result.structuredContent)) return true;
+    if (retained) return false;
+    retained = true;
+    return true;
+  });
+  return { ...result, content };
+}
+
+export function projectDshResponseFrame(line, pendingToolCallIds) {
+  const frame = parseFrame(line);
+  if (
+    !frame ||
+    !Object.hasOwn(frame, "id") ||
+    Object.hasOwn(frame, "method") ||
+    (!Object.hasOwn(frame, "result") && !Object.hasOwn(frame, "error"))
+  ) return line;
+  const key = requestIdKey(frame.id);
+  if (!pendingToolCallIds.delete(key)) return line;
+  if (!isRecord(frame.result)) return line;
+  const projected = projectDshCallResult(frame.result);
+  return projected === frame.result ? line : JSON.stringify({ ...frame, result: projected });
+}
+
+function usageError(message) {
+  throw new Error(`${message}; usage: mcp-result-adapter.mjs --binary <server> -- [args...]`);
+}
+
+function parseAdapterArgs(argv) {
+  if (argv[0] !== "--binary" || typeof argv[1] !== "string" || argv[1].length === 0) {
+    usageError("--binary is required");
+  }
+  if (argv[2] !== "--") usageError("expected -- before MCP server arguments");
+  return { binary: argv[1], childArgs: argv.slice(3) };
+}
+
+export function runAdapter(argv = process.argv.slice(2)) {
+  const { binary, childArgs } = parseAdapterArgs(argv);
+  const child = spawn(binary, childArgs, {
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const pendingToolCallIds = new Set();
+  let adapterFailed = false;
+  let forwardedSignal;
+  let terminationTimer;
+
+  child.stderr.pipe(process.stderr);
+
+  const clientLines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const serverLines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+
+  function childIsRunning() {
+    return child.exitCode === null && child.signalCode === null;
+  }
+
+  function terminateChild(signal) {
+    if (!childIsRunning()) return;
+    child.kill(signal);
+    if (terminationTimer !== undefined) return;
+    terminationTimer = setTimeout(() => {
+      terminationTimer = undefined;
+      if (childIsRunning()) child.kill("SIGKILL");
+    }, CHILD_TERMINATION_GRACE_MS);
+  }
+
+  function failAdapter(error) {
+    if (adapterFailed) return;
+    adapterFailed = true;
+    process.exitCode = 1;
+    process.stderr.write(
+      `xuanling-dsh-result-adapter: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    clientLines.close();
+    serverLines.close();
+    terminateChild("SIGTERM");
+  }
+
+  clientLines.on("line", (line) => {
+    const request = requestMethodAndId(line);
+    if (request?.method === "tools/call") pendingToolCallIds.add(request.id);
+    if (!child.stdin.write(`${line}\n`)) clientLines.pause();
+  });
+  clientLines.once("close", () => {
+    if (!child.stdin.destroyed) child.stdin.end();
+  });
+  child.stdin.on("drain", () => clientLines.resume());
+  child.stdin.on("error", (error) => {
+    if (child.exitCode === null && child.signalCode === null) failAdapter(error);
+  });
+
+  serverLines.on("line", (line) => {
+    if (adapterFailed) return;
+    try {
+      validateChildFrame(line);
+      const projected = projectDshResponseFrame(line, pendingToolCallIds);
+      if (!process.stdout.write(`${projected}\n`)) serverLines.pause();
+    } catch (error) {
+      failAdapter(error);
+    }
+  });
+  process.stdout.on("drain", () => serverLines.resume());
+
+  child.once("error", failAdapter);
+  child.once("close", (code, signal) => {
+    if (terminationTimer !== undefined) clearTimeout(terminationTimer);
+    clientLines.close();
+    serverLines.close();
+    if (adapterFailed) return;
+    if (forwardedSignal !== undefined) {
+      process.exitCode = 1;
+      return;
+    }
+    if (code !== 0 || signal !== null) {
+      process.exitCode = code ?? 1;
+      return;
+    }
+    if (pendingToolCallIds.size > 0) {
+      failAdapter(new Error(`child exited with ${pendingToolCallIds.size} unresolved tools/call request(s)`));
+    }
+  });
+
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.once(signal, () => {
+      if (forwardedSignal !== undefined) return;
+      forwardedSignal = signal;
+      clientLines.close();
+      terminateChild(signal);
+    });
+  }
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) runAdapter();

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@xuanling-rs/xuanling-dsh-tools",
-  "version": "0.2.2",
-  "description": "XuanLing bootstrap placeholder; replaced by the verified 0.2.3 release.",
+  "version": "0.2.4",
+  "description": "DeepSeek Harness bundle: mount the XuanLing MCP server (xuanling-mcp binary) as native mcp__xuanling__* tools through the official @deepseek-ai/dsh-mcp-client bridge. Additive variant: built-in tools stay enabled.",
   "license": "MIT",
   "private": false,
+  "dependencies": {
+    "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.5",
+    "@xuanling-rs/xuanling-mcp": "0.2.4"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README-ZH.md",
+    "cordis.patch.yml",
+    "mcp-result-adapter.mjs"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
   "engines": {
     "node": ">=22.14.0"
   },
@@ -18,6 +34,10 @@
   },
   "publishConfig": {
     "access": "public",
+    "provenance": true,
     "registry": "https://registry.npmjs.org"
+  },
+  "xuanlingRelease": {
+    "sourceCommit": "3fc3e6304a4839de292bf7470f0dbf3f6a7ebe59"
   }
 }