@deepseek-ai/dsh-native-command 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/native-command/README.md
+README.md: dd9d1ddaf817b2ff77ec0cd01710053e918b4296
+README.zh.md: 3ff8a392f2c511295adb0bf5f62b6e0527cbaea6

package/README.md

@@ -0,0 +1,27 @@
+# dsh-native-command
+
+English | [中文](README.zh.md)
+
+A **zero-dependency no-shell `execFile` runner** shared by host-native OS integrations: one `runNativeCommand(command, args, signal)` call spawns the executable directly (never a shell string), captures utf8 stdout/stderr, propagates the caller's abort into child termination, and hides the transient console window on Windows. Failures reject with the exit `code` and both captured streams attached, so callers classify (missing tool, cancelled, real failure) without re-running anything.
+
+Its two consumers are the host-side native integrations: the [`directory-picker-native`](../../host/directory-picker-native/README.md) backend's OS chooser commands and the gateway's open-with-default-application hand-off ([`dsh-host-apiproxy`](../../host/apiproxy/README.md) `host.openPath`). The `NativeCommandRunner` type is their injectable command boundary.
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state, emits no events.
+
+## Surface
+
+```ts
+import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
+```
+
+## Model Experience
+
+None, as this is host-side subprocess plumbing; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No output bounding** — both streams buffer unbounded in memory; every current caller invokes small native tools whose output is a path or an error line. Adopt `dsh-retention` bounding before pointing this at commands with meaningful output volume.

package/README.zh.md

@@ -0,0 +1,27 @@
+# dsh-native-command
+
+[English](README.md) | 中文
+
+宿主原生 OS 集成共享的**零依赖免 shell `execFile` 运行器**：一次 `runNativeCommand(command, args, signal)` 调用直接 spawn 可执行文件（绝不拼 shell 字符串），以 utf8 捕获 stdout/stderr，把调用方的 abort 传播为子进程终止，并在 Windows 上隐藏瞬时控制台窗口。失败时，调用会以错误拒绝；该错误附带退出 `code` 与两路已捕获输出，调用方无需重跑即可分类（工具缺失、已取消、真实失败）。
+
+它的两个消费方都是宿主侧原生集成：[`directory-picker-native`](../../host/directory-picker-native/README.md) 后端的 OS 选择器命令，以及网关将路径交由默认应用打开的操作（[`dsh-host-apiproxy`](../../host/apiproxy/README.md) 的 `host.openPath`）。`NativeCommandRunner` 类型是这些调用方的可注入命令边界。
+
+它是**库，不是服务或插件**：没有 `ctx`、不注册任何东西、不持有状态、不发事件。
+
+## 接口面
+
+```ts
+import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
+```
+
+## 模型体验
+
+无；这是宿主侧子进程管道，这里没有任何东西进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **不做输出限量**——两路流在内存中无界缓冲；当前每个调用方只运行输出为一个路径或一行错误的小型原生工具。把它指向输出量可观的命令之前，先接入 `dsh-retention` 限量。

package/lib/index.js

@@ -0,0 +1,38 @@
+import { execFile } from "node:child_process";
+//#region lib/types/index.js
+/**
+* Shared no-shell `execFile` runner for host-native OS integrations (the
+* native directory chooser, the open-with-default-application hand-off):
+* utf8 stdio capture, abort propagation, Windows console hide. A library,
+* not a plugin — no ctx, no state, no events.
+* @module @deepseek-ai/dsh-native-command
+*/
+/**
+* Run a host command with utf8 stdio, abort propagation, and Windows hide.
+* @param command - executable path or PATH name.
+* @param args - argv (never a shell string).
+* @param signal - caller/connection lifetime; abort terminates the child.
+* @returns captured stdout/stderr on exit 0.
+*/
+const runNativeCommand = (command, args, signal) => new Promise((resolve, reject) => {
+	execFile(command, [...args], {
+		encoding: "utf8",
+		signal,
+		windowsHide: true
+	}, (error, stdout, stderr) => {
+		if (error !== null) {
+			reject(Object.assign(new Error(error.message, { cause: error }), {
+				code: error.code,
+				stdout,
+				stderr
+			}));
+			return;
+		}
+		resolve({
+			stdout,
+			stderr
+		});
+	});
+});
+//#endregion
+export { runNativeCommand };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-native-command`.
+* @module @deepseek-ai/dsh-native-command/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-native-command";
+/** Cordis companion plugin name. */
+const name = "native-command-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: each run is one stateless child-process round trip
+* with no owned event stream or mutable runtime data; behavior is enforced by
+* unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared no-shell `execFile` runner for host-native OS integrations (the
+ * native directory chooser, the open-with-default-application hand-off):
+ * utf8 stdio capture, abort propagation, Windows console hide. A library,
+ * not a plugin — no ctx, no state, no events.
+ * @module @deepseek-ai/dsh-native-command
+ */
+/** Testable command boundary; native implementations never invoke a shell. */
+export type NativeCommandRunner = (command: string, args: readonly string[], signal: AbortSignal) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * @param command - executable path or PATH name.
+ * @param args - argv (never a shell string).
+ * @param signal - caller/connection lifetime; abort terminates the child.
+ * @returns captured stdout/stderr on exit 0.
+ */
+export declare const runNativeCommand: NativeCommandRunner;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-native-command`.
+ * @module @deepseek-ai/dsh-native-command/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "native-command-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-native-command",
+  "description": "Zero-dependency no-shell execFile runner for host-native OS integrations: utf8 stdio capture, abort propagation, Windows hide",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/native-command"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  }
+}