README.md 4.6 KB
description: "A zero-dependency no-shell execFile runner for host-native OS integrations, with utf8 stdio capture, abort propagation, and a hidden console window on Windows."
kind: "package-library"
@deepseek-ai/dsh-native-command
English | 中文
Summary
dsh-native-command runs a host executable directly — never through a shell string — and captures its utf8 stdout and stderr. The caller's abort signal terminates the child, and on Windows the transient console window stays hidden. A failed run rejects with the exit code and both captured streams attached, so callers classify a missing tool, a cancellation, or a real failure without re-running anything. The host-side consumers are the native directory chooser and the open-with-default-application hand-off. It is a library, not a plugin: no ctx, no state, no events.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Use this runner when a host-side integration must execute one native command and needs its output, its failure, or both — and must never involve a shell.
Running a command
import { runNativeCommand } from '@deepseek-ai/dsh-native-command'
declare const script: string
declare const signal: AbortSignal
const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal)
On exit 0 the call resolves with captured stdout and stderr. On any failure it rejects with the exit code and both captured streams attached, so a caller can tell a missing tool (ENOENT), a cancellation (ABORT_ERR), and a real command failure apart without re-running the command.
Injecting the command boundary
The NativeCommandRunner type is the injectable command boundary for host integrations: pass the function (or a wrapper) where the integration needs a testable seam, so tests can substitute a fake runner.
Understand the implementation
Implementation internals — click to expand
The runner is a thin wrapper over Node's `execFile` with three fixed choices: utf8 encoding, abort propagation, and Windows console hiding. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | `runNativeCommand` and the `NativeCommandRunner` type — the whole package | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; each run is one stateless child-process round trip) | ### What execFile gives the runner `execFile` spawns the executable directly with an argv array — no shell string, no shell interpretation of the arguments. The `signal` option terminates the child when the caller's abort fires; `windowsHide` suppresses the transient console window on Windows. On a non-zero exit or spawn error, the callback attaches `code`, `stdout`, and `stderr` to the rejected error and keeps the original error as `cause`.Further Exploration
Read these pages when you need the consumers or the general subprocess capability this utility deliberately is not.
- Native directory picker — the OS chooser commands this runner executes.
- Host API proxy — the open-with-default-application hand-off this runner serves.
- Subprocess capability — the general subprocess seam, of which this package is not a part.
Model Experience
None, as the host-side subprocess runner registers nothing model-facing.
KV Cache effect
Nothing here enters a request prefix; this package neither assembles nor sends a provider request.
Known Limitations and Deferred Work
These limits define when this runner is not the right tool. They are current package constraints, not a task backlog.
- 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-output-retentionbounding before pointing this at commands with meaningful output volume.